From 2b592b36666e1a722bda1758a25c45e16d4f13f0 Mon Sep 17 00:00:00 2001 From: Wolfgang Maier Date: Wed, 12 Mar 2025 17:15:44 +0100 Subject: [PATCH 1/2] Update mentions of Galaxy in intro, about and footer --- docs/conf.py | 8 ++++---- docs/content/about.rst | 4 +--- docs/index.rst | 8 ++++---- 3 files changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 5a741a451e..48d433907b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,7 @@ import tomllib # to allow readthedocs to compile without installing some dependencies -import mock +from unittest import mock # MOCK_MODULES = ['numpy', 'numpy.ma', 'scipy', 'pyBigWig'] MOCK_MODULES = ['pyBigWig', 'py2bit', 'plotly', 'plotly.offline', 'plotly.graph_objs', 'plotly.figure_factory'] @@ -96,9 +96,9 @@ def get_version(): # An rst epilog to apper at the end of every page rst_epilog = """ -+----------------------------------------------------------------+-------------------------------------------------------------+ -| `deepTools Galaxy `_. | `code @ github `_. | -+----------------------------------------------------------------+-------------------------------------------------------------+ ++----------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `code @ github `__ | `report issues `__ | `learn to analyze epigenetics data with deepTools and Galaxy `__ | ++----------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ """ # The language for content autogenerated by Sphinx. Refer to documentation diff --git a/docs/content/about.rst b/docs/content/about.rst index 130b29928e..3803e76213 100644 --- a/docs/content/about.rst +++ b/docs/content/about.rst @@ -11,10 +11,8 @@ Please cite deepTools as follows: Where deepTools are used: * DEEP consortium -* public Galaxy server hosted at ``_. -* public Galaxy instance hosted by the Max-Planck-Institute for Immunobiology and Epigenetics: deeptools.ie-freiburg.mpg.de +* public Galaxy servers `usegalaxy.org `__, `Galaxy Europe `__ and `Galaxy Australia `__. * in-house Galaxy instance of the Max-Planck-Institute for Immunobiology and Epigenetics -* Galaxy instance of the University of Freiburg, Germany * Galaxy instance of the ICGMB, Strasbourg, France * Galaxy instance of LCSB and HPC @ Uni.lu, Belval, Luxembourg diff --git a/docs/index.rst b/docs/index.rst index 4eac3e9ee3..1698fd6960 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,12 +4,12 @@ deepTools: *tools for exploring deep sequencing data* .. image:: images/start_collage.png -deepTools is a **suite of python tools** particularly developed for the +deepTools is a **suite of tools** particularly developed for the efficient analysis of high-throughput sequencing data, such as ChIP-seq, RNA-seq or MNase-seq. There are 3 ways for using deepTools: -* **Galaxy usage** -- our public `deepTools Galaxy server `_ let's you use the deepTools within the familiar Galaxy framework without the need to master the command line +* **Galaxy usage** -- deepTools comes with first-class integration for the `Galaxy platform `__ and is available for zero-install, browser-based use on major public Galaxy servers including `usegalaxy.org `__, `Galaxy Europe `__ and `Galaxy Australia `__. * **command line usage** -- simply download and install the tools (see :doc:`content/installation` and :doc:`content/list_of_tools`) * **API** -- make use of your favorite deepTools modules in your own python programs (see :doc:`content/api`) @@ -18,12 +18,12 @@ currently available. .. image:: images/start_workflow.png -If the file names in the figure mean nothing to you, +If the file format names in the figure mean nothing to you, please make sure to check our :doc:`content/help_glossary`. deepTools 4.0.0 --------------- -As of deepTools 4.0.0, quite big changes have been made to the computation backend (which is now written in `rust `_). +As of deepTools 4.0.0, quite big changes have been made to the computation backend (which is now written in `rust `__). The main idea behind this change is to make some tools faster and more robust. Useability of the tools are not affected. But note that the output (read precision) might be slightly different than before. From 217a252a169ba1d59c1ca5e8b9008371855f1e13 Mon Sep 17 00:00:00 2001 From: Wolfgang Maier Date: Fri, 28 Mar 2025 17:27:39 +0100 Subject: [PATCH 2/2] Modernize and restructure the Galaxy parts of the documentation --- docs/content/example_usage.rst | 14 +-- docs/content/galaxy_usage.rst | 23 +++++ docs/content/help_faq.rst | 32 ++++++- docs/content/help_faq_galaxy.rst | 133 +++++++++++++++++------------ docs/content/help_galaxy_intro.rst | 112 ------------------------ docs/index.rst | 3 +- 6 files changed, 141 insertions(+), 176 deletions(-) create mode 100644 docs/content/galaxy_usage.rst delete mode 100644 docs/content/help_galaxy_intro.rst diff --git a/docs/content/example_usage.rst b/docs/content/example_usage.rst index 57e37452db..6455eaffa2 100644 --- a/docs/content/example_usage.rst +++ b/docs/content/example_usage.rst @@ -6,14 +6,14 @@ Example usage .. toctree:: :maxdepth: 1 - example_step_by_step + galaxy_usage example_gallery How we use deepTools for ChIP-seq analyses ------------------------------------------- -To get a feeling for what deepTools can do, we'd like to give you a brief glimpse into how we typically use deepTools for ChIP-seq analyses. For more detailed exampes and descriptions of the tools, simply follow the respective links. +To get a feeling for what deepTools can do, we'd like to give you a brief glimpse into how we typically use deepTools for ChIP-seq analyses. For more detailed examples and descriptions of the tools, simply follow the respective links. .. note:: While some tools, such as :doc:`tools/plotFingerprint`, specifically address ChIP-seq-issues, the majority of tools is widely applicable to deep-sequencing data, including RNA-seq. @@ -22,7 +22,7 @@ To get a feeling for what deepTools can do, we'd like to give you a brief glimps As shown in the flow chart above, our work usually begins with one or more :ref:`FASTQ ` file(s) of deeply-sequenced samples. After preliminary quality control using -`FASTQC `__, +`FASTQC `__ or `Falco `__, we align the reads to the reference genome, e.g., using `bowtie2 `__. The standard output of bowtie2 (and other mapping tools) is in the form of sorted and indexed :ref:`BAM` files @@ -54,7 +54,7 @@ For paired-end samples, we often additionally check whether the fragment sizes a 3. **GC-bias check** (:doc:`tools/computeGCBias`). Many sequencing protocols require several rounds of PCR-based DNA amplification, which often introduces notable bias, due to many DNA polymerases preferentially amplifying GC-rich templates. Depending on the sample (preparation), the GC-bias can vary significantly and we routinely check its extent. When we need to compare files with different GC biases, we use the :doc:`tools/correctGCBias` module. - See the paper by `Benjamini and Speed `__ for many insights into this problem. + See the paper by `Benjamini and Speed `__ for many insights into this problem. .. image:: ../images/test_plots/ExampleCorrectGCBias.png :width: 50% @@ -62,7 +62,7 @@ For paired-end samples, we often additionally check whether the fragment sizes a 4. **Assessing the ChIP strength**. We do this quality control step to get a feeling for the signal-to-noise ratio in samples from ChIP-seq experiments. It is based on the insights published by `Diaz et - al. `_ + al. `_ .. image:: ../images/test_plots/fingerprints.png :width: 70% @@ -75,10 +75,10 @@ from their significantly decreased size: - useful for data sharing and storage - intuitive visualization in Genome Browsers (e.g. - `IGV `__) + `IGV, the Integrative Genomics Viewer `__) - more efficient downstream analyses are possible The deepTools modules :doc:`tools/bamCompare` and :doc:`tools/bamCoverage` not only allow for simple conversion of BAM to bigWig (or :ref:`bedGraph` for that matter), but also for normalization, such that different samples can be compared despite differences in their sequencing depth. -Finally, once all the converted files have passed our visual inspections (e.g., using the `Integrative Genomics Viewer `_), the fun +Finally, once all the converted files have passed our visual inspections (e.g., using `IGV `_), the fun of downstream analysis with :doc:`tools/computeMatrix`, :doc:`tools/plotHeatmap` and :doc:`tools/plotProfile` can begin! diff --git a/docs/content/galaxy_usage.rst b/docs/content/galaxy_usage.rst new file mode 100644 index 0000000000..4f2430d64f --- /dev/null +++ b/docs/content/galaxy_usage.rst @@ -0,0 +1,23 @@ +Using deepTools within Galaxy +================================ + +What is Galaxy? +--------------- + +`Galaxy `_ is a tremendously useful platform for performing data analysis in bioinformatics and beyond through a web-based graphical user interface. Galaxy offers access to a large variety of bioinformatics and other computational tools that can be used without computer programming experiences. + +deepTools is available on major public instances of Galaxy. + +Learning to handle sequencing data and to analyze it with deepTools through Galaxy +---------------------------------------------------------------------------------- + +The `Galaxy Training Network `__ has compiled a very extensive set of training materials (slides, recorded videos and written tutorials) that you can use for self-paced learning. + +Their `Learning Pathway: Epigenetics data analysis with Galaxy `__, in particular, assumes no prior knowledge of Galaxy (so you may be able to skip some of the material if you have worked on the platform before) and showcases most of deepTools' functionality in close to real-world analysis tasks. + +You should be able to follow the hands-on parts of the material on any Galaxy instance that offers deepTools. + +Still having questions? +----------------------- + +Check out the :doc:`help_faq_galaxy` section of this documentation. diff --git a/docs/content/help_faq.rst b/docs/content/help_faq.rst index b6e397e6dc..3455153b1d 100644 --- a/docs/content/help_faq.rst +++ b/docs/content/help_faq.rst @@ -1,7 +1,7 @@ General FAQ =========== -.. tip:: For support or questions please post to `Biostars `__. For bug reports and feature requests please open an issue ``__. +.. tip:: For support or questions please post to `Biostars `__. For bug reports and feature requests please open an issue on `github `__. .. Note:: We also have a :doc:`help_faq_galaxy` with questions that are more specific to Galaxy rather than deepTools usage. @@ -306,4 +306,34 @@ The 2bit files of most genomes can be found `here `__). +--------------------------------------------------------------------------- + +.. _igv-setup: + +How to set up IGV for data visualization? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `Integrative Genomics Viewer IGV `__ is a powerful and rather user-friendly tool to visualize positional genomic data with respect to a reference genome. It can handle many of the output formats generated during a :doc:`typical deepTools-based analysis ` like :ref:`BAM`, :ref:`bigWig`, :ref:`BED` and :ref:`bedGraph` format. + +We recommend downloading the `desktop version of IGV `__, which is free and open-source software, for your operating system, then to start using it: + +1. Unpack the downloaded archive and move the contained IGV folder wherever is convenient for you, or, on Windows, run the downloaded installer. +2. Start IGV according to the instructions in the ``readme.txt`` file inside the IGV folder, or, on Windows, simply open the installed desktop application. +3. Follow the IGV `Quick Start instructions `__ to load your data and its corresponding reference genome. + +Here's a screenshot of a typical bigWig file display in IGV: + +.. image:: ../images/Gal_FAQ_IGV.png + +.. Tip:: We typically convert :ref:`BAM` and :ref:`bedGraph` files to :ref:`bigWig` format before loading them into IGV. + + The :ref:`bigWig` format is internally indexed and can therefor be loaded more efficiently than data in the :ref:`bedGraph` format. + Conversion from :ref:`BAM` to :ref:`bigWig` format comes with a very significant decrease in data size, while preserving relevant information (coverage) for many data interpretation purposes. + +.. Note:: If you want to visualize :ref:`BAM` format directly (because you need sequenced read-level information), you need to provide the BAM index file alongside the BAM file as `explained in the IGV documentation `__. + + This is of no relevance if you're :ref:`using IGV from Galaxy ` since Galaxy will handle the index file transparently for you. + + + diff --git a/docs/content/help_faq_galaxy.rst b/docs/content/help_faq_galaxy.rst index 9d3e2d058a..d3b4df1400 100644 --- a/docs/content/help_faq_galaxy.rst +++ b/docs/content/help_faq_galaxy.rst @@ -1,116 +1,141 @@ Galaxy-related FAQ =================== +The Galaxy Project is maintaining an impressive `FAQ collection `__ regarding usage of their platform. + +Here we are only highlighting a few that deepTools users have happened to ask before. + .. contents:: :local: I've reached my quota - what can I do to save some space? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. make sure that all the data sets you deleted are **permanently** eliminated from our disks: go to the history option button and select "Purge deleted data sets", then hit the "refresh" button on top of your history panel -2. download all data sets for which you've completed the analysis, then remove the data sets (click on the "x" and then **make sure they're purged** (see above)). - ----------------------------------------------------------------------- - -Copying from one history to another doesn't work for me - the data set simply doesn't show up in the target history! -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +See Galaxy FAQ: `How can I reduce quota usage ... `__. -Once you've copied a data set from one history to another, check two things: - * do you see the destination history in your history panel, i.e. does the title of the current history panel match the name of the destination history you selected in the main frame? - * hit the refresh button - -.. image:: ../images/Gal_historyReload.png +In addition, we recommend you to avoid multiple uploads of the same data to different histories. +The preferred way is to **copy** the data sets between histories instead, which will not consume extra quota. This Galaxy FAQ: `Copy a dataset between histories `__ explains different ways of doing so. ---------------------------------------------------------------------- -How can I use a published workflow? +How can I find and use published deepTools workflows? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You **must register** if you want to use the workflows within `deepTools Galaxy `__. ("User" --> "Register" - all you have to supply is an email address). Make sure to read the Terms of Use, though! +`WorkflowHub `__ and `Dockstore `__ are two excellent places to look for scientific workflows. -You can find workflows that are public or specifically shared with you by another user via "Shared Data" --> "Published Workflows". Click on the triangle next to the workflow you're interested in and select "import". +To search specifically for Galaxy workflows that make use of deepTools, you can use the following queries: -.. image:: ../images/GalHow_wf01.png +- on WorkflowHub: ``__ +- on Dockstore: ``__ +.. Note:: Both WorkflowHub and Dockstore are general workflow registries on which anyone can deposit workflows. -A green box should appear, there you select "start using this workflow", which should lead you to your own workflow menu (that you can always access via the top menu "Workflow"). Here, you should now see a workflow labeled "imported: ....". If you want to use the workflow right away, click on the triangle and select "Run". The workflow should now be available within the Galaxy main data frame and should be waiting for your input. + If you are looking for high-quality workflows pay attention to workflow authors and submitters to see if you recognize them. -.. image:: ../images/GalHow_wf02.png + Within the Galaxy ecosystem the `Intergalactic Workflow Commission (IWC) `__ is an organization aiming at publishing workflows adhering to best-practices and standards in their field. They register their workflows at both Dockstore and WorkflowHub so IWC-submitted workflows can be one thing to look out for on these registries. ----------------------------------------------------------------------- +Once you have found a workflow you want to use, you can import it onto a Galaxy instance of your choice by following one of these instructions: + +- Galaxy FAQ: `Import a workflow from WorkflowHub `__ +- Galaxy FAQ: `Import a workflow from Dockstore `__ -I would like to use one of your workflows - not in the deepTools Galaxy, but in the local Galaxy instance provided by my institute. Is that possible? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This will import the workflow to your list of workflows. Note that it will also carry a little blue-white shield icon next to its name, which indicates that this is an original workflow version imported from a TRS server. If you ever modify the workflow with Galaxy’s workflow editor, it will lose this indicator. -Yes, it is possible. The only requirement is that your local Galaxy has a recent installation of deepTools. +You can then follow the Galaxy FAQ on `Running a workflow `__ to use the imported workflow. -Go to the workflows, click on the ones you're interested in and go to "Download". This will save the workflows into .ga files on your computer. Now go to your local Galaxy installation and login. Go to the workflow menu and select "import workflow" (top right hand corner of the page). Click on "Browse" and select the saved workflow. If you have the same tool versions installed in your local Galaxy, these workflows should work right away. +.. Note:: If you see error messages during the import or when trying to run the workflow, a likely reason is that the Galaxy server you are working on does not have all the tools installed that the workflow wants to use. + + If your workflow is from the IWC organization it should normally be usable on all major public Galaxy servers. ---------------------------------------------------------------------- ``plotProfile`` says that one option will only work if "computeMatrix was run with --missingDataAsZero". How can I find out whether I ran ``computeMatrix`` that way? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Galaxy keeps track of everything you do. To see which options you chose to generate a specific data set, simply click on the "info" button. +Galaxy keeps track of everything you do. To see which options you chose to generate a specific dataset, you can use Galaxy's `"Run Job Again" `__ functionality to restore the tool interface with the same settings that you configured to create any of your existing datasets. -.. image:: ../images/Gal_FAQ_info.png +Alternatively, you can click the ``(i)`` *Dataset Details* icon on the dataset in question, then check the *"Tool Parameters"* section of the resulting page. ---------------------------------------------------------------------- -How can I have a look at the continuous read coverages from bigWig files? Which genome browser do you recommend? +.. _galaxy-visualize: + +How can I visualize bigWig/bed/bam datasets from Galaxy? Which genome browser do you recommend? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -There are 2 popular genome browsers for visualizing continuous data: `UCSC `__ and `IGV `__. +There are 2 popular genome browsers that we recommend for visualizing positional genomic data along its corresponding reference genome: the `Integrative Genomics Viewer IGV `__ and the `UCSC genome browser `__. -IGV (recommended) -~~~~~~~~~~~~~~~~~~~ +IGV +~~~~ -We recommend downloading `IGV `__, which is free for academic use. IGV itself needs an up-to-date Java installation and a considerable amount of RAM. It's usage is rather intuitive and the display can be easily customized. In addition, you can download genome-wide annotation data that can be displayed together with your own data. +This is our recommendation unless you want to visualize your data in relation to the vast amount of annotation tracks available in the UCSC genome browser. This option requires a bit of setup on your local machine, but then provides a rather intuitive, yet flexible user interface. -To display data in IGV, do the following: +To set up IGV for use on your computer, first follow our :ref:`general instructions `. -1. Go to http://www.broadinstitute.org/igv/, register and download IGV -2. Unpack the IGV archive and change to the extracted IGV folder -3. Use the ``igv.bat`` (Windows), ``igv.sh`` (Linux) or ``igv.command`` (OSX) to start IGV (for more information please read the included ``readme.txt`` file or the IGV documentation). -4. Choose the genome version of the file(s) you would like to visualize (e.g. dm3) **THIS IS THE MOST IMPORTANT STEP!** IGV will not detect the genome version automatically, i.e. if you select mm9 but your file is based on human data, it will still be displayed without an error message (but with the wrong positions, obviously!) -5. Go to your deepTools Galaxy server (http://deeptools.ie-freiburg.mpg.de/) and navigate to your data set of choice -6. Click on your data set so that you see its details like in the screenshot below (**Keep in mind that not all datasets can be visualized in IGV or UCSC.** We recommend to use :ref:`bigwig` or :ref:`bed` files for visualization.) +Then to display data from any Galaxy server in your local IGV: -.. image:: ../images/Gal_FAQ_IGV_dataset.png +1. Make sure you have started IGV on your computer. -Now click on **"display with IGV local"** to visualize your data set in IGV that should already be running on your computer. +2. In Galaxy, expand the dataset that you would like to visualize by clicking on it. -.. Note:: "display with IGV Web current" can be used if you do not have an installed IGV. It will start an IGV web start version. **We do *not* recommend that option**. +3. (highly recommended) In the expanded view, make sure you have `set the dataset's reference genome/database (dbkey) `__ correctly. -Here's a screenshot of a typical bigWig file display: + .. important:: Obviously it is of importance to visualize the data against the **correct** reference genome! + Galaxy will use the genome/database information of the dataset to load what it assumes is the correct reference genome in IGV for you. + If you haven't previously installed that genome, IGV will download it for you automatically. -.. image:: ../images/Gal_FAQ_IGV.png + **Careful**: if the genome/database information is **not** set (i.e. Galaxy shows a ``?``) for your dataset, IGV will just use whatever reference genome it has loaded at the moment to visualize your data against! +4. Click on the *Visualize* icon attached to your dataset and select *"display with IGV (local)"* from the central panel (the *web_current* option, if shown, is not recommended). -For more information, check out the `IGV documentation `__. +5. Switch over to IGV and wait for Galaxy to complete the initial communication with IGV. +6. Check again that the expected reference genome has been selected in IGV, then start exploring your data just as you would for local data. -UCSC -~~~~~~~~ -There is a direct link from within deepTools Galaxy to stream a data set to UCSC. You can find it in the data set tiles: "display at UCSC", like here: +UCSC Genome Browser +~~~~~~~~~~~~~~~~~~~~ -.. image:: ../images/Gal_FAQ_UCSC_dataset.png +This option lets you visualize your data without any local setup. All data transfer happens only between the Galaxy server and the UCSC genome browser. The resulting web-based visualization may be less responsive and may not look as nice as the one using IGV, but you will have all annotation tracks stored at UCSC at your disposal to display them alongside your data. +The steps to display data from any Galaxy server in the UCSC genome browser are very similar to the ones described above for IGV: -Click on "main" and the UCSC browser should open within a new window, displaying the data set that you chose. -The default setting for bigWig files is the "dense" display that looks like a heatmap. +1. In Galaxy, expand the dataset that you would like to visualize by clicking on it. +2. In the expanded view, make sure you have `set the dataset's reference genome/database (dbkey) `__ correctly. + + .. important:: Obviously it is of importance to visualize the data against the **correct** reference genome! + Galaxy will use the genome/database information of the dataset to set what it assumes is the correct reference genome in the UCSC genome browser for you. + +3. Click on the *Visualize* icon attached to your dataset and select *"display at UCSC (main)"* from the central panel. + + .. Tip:: If the option doesn't appear, verify that the dataset's format is of a supported type (e.g. bigwig, bed or bam) and that its reference genome/database (dbkey) is set (see the previous step). + +4. Wait for Galaxy to complete the initial communication with the UCSC server. +5. Check again that the expected reference genome is mentioned in the title of the browser view, then start exploring your data. + +The default setting for user-provided custom tracks in the UCSC genome browser is the "dense" display which looks like a heatmap for bigwig and bam data. .. image:: ../images/Gal_FAQ_UCSC01.png +**Usage hints** + +- If you would like to display bigwig data in a "valley-mountain" fashion or bam data as a stack of reads, go to the drop-down menu underneath your custom track and choose "full", then click *"Refresh"* in the section title or at the very bottom of the page. + +- The UCSC genome browser remembers the state of your session from previous browser tabs. + + .. Tip:: This means that to view more than one dataset from Galaxy simultaneously, you can just go back to Galaxy and repeat the above steps. + The new genome browser view will show the newly selected data alongside all previously configured tracks. + +- UCSC has large amounts of public data that you can display together with your data. -If you would like to display the continuous profile in a "valley-mountain" fashion like the one shown in the IGV screenshot, go to the drop-down menu underneath your custom track and choose "full". + You can configure these public tracks by scrolling down the page, beyond your custom track section. -UCSC has large amounts of public data that you can display which you can find by scrolling down the page, beyond your custom track entry. For more information on how to use the UCSC Genome Browser, go `here `__. +- The UCSC `genome browser user guide `__ has a lot more information on what you can do with this tool. -**Known issues with UCSC** +- **Known issue with chromosome names**: -* **chromosome naming**: UCSC expects chromosome names to be indicated in the format "chr"Number, e.g. chr1. If you mapped your reads to a non-UCSC-standard genome, chances are that chromosomes are labeled just with their number. bigWig files generated from these BAM files will not be recognized by UCSC, i.e. you will see the data set name, but no signal. -* **no upload of bigWig files from your hard drive**: to minimize the computational strains, UCSC relies on streaming bigWig files (i.e. there's no need to load the entire file at once, the browser will always just load the data for the specific region a user is looking at). + The UCSC genome browser expects chromosome names to be indicated in the format *"chr"*, e.g. chr1. + If you mapped your reads to a non-UCSC-standard genome, chances are that chromosomes are labeled just with their number. + Such data will not be recognized by the genome browser, i.e. you will see just the track name, but no signal. ---------------------------------------------------------------------- diff --git a/docs/content/help_galaxy_intro.rst b/docs/content/help_galaxy_intro.rst deleted file mode 100644 index 7ba1b913d1..0000000000 --- a/docs/content/help_galaxy_intro.rst +++ /dev/null @@ -1,112 +0,0 @@ -Using deepTools within Galaxy -================================ - -`Galaxy `_ is a tremendously useful platform developed by the Galaxy Team at Penn State and the Emory University. This platform is meant to offer access to a large variety of bioinformatics tools that can be used without computer programming experiences. That means, that the basic features of Galaxy will apply to every tool, i.e. every tool provided within a Galaxy framework will look very similar and will follow the concepts of Galaxy. - -Our publicly available deepTools Galaxy instance can be found here: -`deeptools.ie-freiburg.mpg.de `_. -This server also contains some additional tools that will enable users to analyse and visualize data from high-throughput sequencing experiments, starting from aligned reads. - -**Table of content** - -.. contents:: - :local: - -.. toctree:: - :maxdepth: 2 - - help_galaxy_dataup - -.. toctree:: - :maxdepth: 2 - - help_galaxy_deeptools - - - -Basic features of Galaxy -------------------------- - -Galaxy is a web-based platform for data intensive, bioinformatics-dependent research and it is being developed by Penn State and John Hopkins University. The original Galaxy can be found `here `_. - -Since it is impossible to meet all bioinformatics needs -- that can range from evolutionary analysis to data from mass spectrometry to high-throughput DNA sequencing (and way beyond) -- with one single web server, many institutes have installed their own versions of the Galaxy platform tuned to their specific needs. - -Our `deepTools Galaxy `__ is such a specialized server dedicated to the analysis of high-throughput DNA sequencing data. The overall makeup of this web server, however, is the same as for any other Galaxy installation, so if you've used Galaxy before, you will learn to use deepTools in no time! - -The start site -^^^^^^^^^^^^^^^ - -Here is a screenshot of what the start site will approximately look like: - -.. image:: ../images/Gal_startsite.png - -The start site contains 4 main features: - -+-------------------+----------------------------------------------------------------------------------------------------------------------------+ -| **Top menu** | Your gateway away from the actual analysis part into other sections of Galaxy, e.g. **workflows** and **shared data**. | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+ -| **Tool panel** | *What can be done?* Find all tools installed in this Galaxy instance | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+ -| **Main frame** | *What am I doing?* This is your main **working space** where input will be required from you once you've selected a tool. | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+ -| **History panel** | *What did I do?* The history is like a **log book**: everything you ever did is recorded here. | -+-------------------+----------------------------------------------------------------------------------------------------------------------------+ - -For those visual learners, here's an annotated screenshot: - -.. image:: ../images/Gal_startsite_with_comments.png - -Details -^^^^^^^^^^^^^^^ - -In the default state of the tool panel you see the **tool categories**, e.g. "Get Data". If you click on them, you will see the **individual tools** belonging to each category, e.g. "Upload File from your computer", "UCSC Main table browser" and "Biomart central server" in case you clicked on "Get Data". To use a tool such as "Upload File from your computer", just click on it. - -The **tool *search* panel** is extremely useful as it allows you to enter a key word (e.g. "bam") that will lead to all the tools mentioning the key word in the tool name. - -Once you've uploaded any kind of data, you will find the history on the -right hand side filling up with green tiles. -Each tile corresponds to one data set that you either uploaded or created. -The data sets can be images, raw sequencing files, text files, tables - virtually anything. -The content of a data set *cannot* be modified - every time you want to change something *within* a data file (e.g. you would like to sort the values or add a line or cut a column), you will have to use a Galaxy tool that will lead to a *new* data set being produced. -This behaviour is often confusing for Galaxy novices (as histories tend to accumulate data sets very quickly), but it is necessary to enforce the strict policy of documenting *every modification* to a given data set. -Eventhough your history might be full of data sets with strange names, you will always be able to track back the source and evolution of each file. -Also, every data set can be downloaded to your computer individually. -Alternatively, you can *download* an entire history or *share* the history with another user. - -Have a look at the following screenshot to get a feeling for how many information Galaxy keeps for you (which makes it very feasible to reproduce any analysis): - -.. image:: ../images/Gal_screenshot_dataSet.png - -Each data set can have 4 different states that are intuitively color-coded: - -.. image:: ../images/Gal_screenshot_dataSetStates.png - -Handling failed files -^^^^^^^^^^^^^^^^^^^^^^ - - If you encounter a failed file after you've run a tool, please do the following steps (**in this order**): - - 1. click on the center button on the lower left corner of the failed data set ``(i)``: did you chose the **correct data files**? - 2. if you're sure that you chose the correct files, hit the ``re-run button`` (blue arrow in the lower left corner) - check again whether your files had the **correct file format**. If you suspect that the format might be incorrectly assigned (e.g. a file that should be a BED file is labelled as a tabular file), click the ``edit button`` (the pencil) of the input data file - there you can change the corresponding attributes - 3. if you've checked your input data and the error is persisting, click on the ``green bug`` (lower left corner of the failed data set) and send the **bug report** to us. You do not need to indicate a valid email-address unless you would like us to get in touch with you once the issue is solved. - -Workflows -^^^^^^^^^^ - -Workflows are Galaxy's equivalent of protocols. -This is a very useful feature as it allows users to *share their protocols and bioinformatic analyses* in a very easy and transparent way. -This is the graphical representation of a Galaxy workflow that can easily be modified via drag'n'drop within the workflows manual (you must be registered with deepTools Galaxy to be able to generate your own workflows or edit published ones). - -.. image:: ../images/Gal_workflow.png - -**More help** - -.. hint:: If you encounter a failing data set (marked in red), please **send a bug report** via the Galaxy bug report button and we will get in touch if you indicate your email address. - -+-------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| `http://wiki.galaxyproject.org/Learn `_ | Help for Galaxy usage in general | -+-------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| `deepTools Galaxy FAQs `_ | Frequently encountered issues with our specific Galaxy instance | -+-------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| `Biostars `__ | For issues not addressed in the FAQs | -+-------------------------------------------------------------------------------+-----------------------------------------------------------------+ diff --git a/docs/index.rst b/docs/index.rst index 1698fd6960..997331ed0c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ efficient analysis of high-throughput sequencing data, such as ChIP-seq, RNA-seq There are 3 ways for using deepTools: -* **Galaxy usage** -- deepTools comes with first-class integration for the `Galaxy platform `__ and is available for zero-install, browser-based use on major public Galaxy servers including `usegalaxy.org `__, `Galaxy Europe `__ and `Galaxy Australia `__. +* **Galaxy usage** -- deepTools comes with first-class integration for the `Galaxy platform `__ and is available for zero-install, browser-based use on major public Galaxy servers including `usegalaxy.org `__, `Galaxy Europe `__ and `Galaxy Australia `__. Check out the :doc:`content/galaxy_usage` page to dive right in. * **command line usage** -- simply download and install the tools (see :doc:`content/installation` and :doc:`content/list_of_tools`) * **API** -- make use of your favorite deepTools modules in your own python programs (see :doc:`content/api`) @@ -43,7 +43,6 @@ Contents: content/advanced_features content/example_usage content/changelog - content/help_galaxy_intro content/help_faq content/help_faq_galaxy content/help_glossary