v4 and Galaxy-specific documentation updates

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 <http://deeptools.ie-freiburg.mpg.de>`_.     | `code @ github <https://github.com/deeptools/deepTools/>`_. |
-+----------------------------------------------------------------+-------------------------------------------------------------+
++----------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| `code @ github <https://github.com/deeptools/deepTools/>`__    | `report issues <https://github.com/deeptools/deepTools/issues>`__  | `learn to analyze epigenetics data with deepTools and Galaxy <https://training.galaxyproject.org/training-material/learning-pathways/epigenetics-data-analysis>`__  |
++----------------------------------------------------------------+--------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 """
 
 # The language for content autogenerated by Sphinx. Refer to documentation

docs/content/about.rst

@@ -11,10 +11,8 @@ Please cite deepTools as follows:
 Where deepTools are used:
 
 * DEEP consortium
-* public Galaxy server hosted at `<https://usegalaxy.org/>`_.
-* public Galaxy instance hosted by the Max-Planck-Institute for Immunobiology and Epigenetics: deeptools.ie-freiburg.mpg.de
+* public Galaxy servers `usegalaxy.org <https://usegalaxy.org/>`__, `Galaxy Europe <https://usegalaxy.eu>`__ and `Galaxy Australia <https://usegalaxy.org.au>`__.
 * 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
 

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 <fastq>`
 file(s) of deeply-sequenced samples. After preliminary quality control using
-`FASTQC <http://www.bioinformatics.babraham.ac.uk/projects/fastqc/>`__,
+`FASTQC <http://www.bioinformatics.babraham.ac.uk/projects/fastqc/>`__ or `Falco <https://github.com/smithlabcode/falco/>`__,
 we align the reads to the reference genome, e.g., using
 `bowtie2 <http://bowtie-bio.sourceforge.net/bowtie2/manual.shtml>`__.
 The standard output of bowtie2 (and other mapping tools) is in the form of sorted and indexed :ref:`BAM` files
@@ -54,15 +54,15 @@ 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 <http://nar.oxfordjournals.org/content/40/10/e72>`__ for many insights into this problem.
+   See the paper by `Benjamini and Speed <https://doi.org/10.1093/nar/gks001>`__ for many insights into this problem.
 
 .. image:: ../images/test_plots/ExampleCorrectGCBias.png
     :width: 50%
 
 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. <http://www.degruyter.com/view/j/sagmb.2012.11.issue-3/1544-6115.1750/1544-6115.1750.xml>`_
+   al. <https://doi.org/10.1515/1544-6115.1750>`_
 
 .. 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 <http://www.broadinstitute.org/igv/>`__)
+   `IGV, the Integrative Genomics Viewer <http://www.broadinstitute.org/igv/>`__)
 -  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 <https://www.broadinstitute.org/igv/>`_), the fun
+Finally, once all the converted files have passed our visual inspections (e.g., using `IGV <https://www.broadinstitute.org/igv/>`_), the fun
 of downstream analysis with :doc:`tools/computeMatrix`, :doc:`tools/plotHeatmap` and :doc:`tools/plotProfile` can begin! 

docs/content/galaxy_usage.rst

@@ -0,0 +1,23 @@
+Using deepTools within Galaxy   
+================================
+
+What is Galaxy?
+---------------
+
+`Galaxy <http://galaxyproject.org/>`_ 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 <https://training.galaxyproject.org/training-material/about.html>`__ 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 <https://training.galaxyproject.org/training-material/learning-pathways/epigenetics-from-zero.html>`__, 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.

docs/content/help_faq.rst

@@ -1,7 +1,7 @@
 General FAQ
 ===========
 
-.. tip:: For support or questions please post to `Biostars <http://biostars.org>`__. For bug reports and feature requests please open an issue `<on github <http://github.com/deeptools/deeptools>`__.
+.. tip:: For support or questions please post to `Biostars <http://biostars.org>`__. For bug reports and feature requests please open an issue on `github <http://github.com/deeptools/deeptools>`__.
 
 .. 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 <http://hgdownload.cse.ucsc.ed
 Search for the .2bit ending. Otherwise, **fasta files can be converted to 2bit** using the UCSC program
 faToTwoBit (available for different platforms from `UCSC here <http://hgdownload.cse.ucsc.edu/admin/exe/>`__).
 
+---------------------------------------------------------------------------
+
+.. _igv-setup:
+
+How to set up IGV for data visualization?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `Integrative Genomics Viewer IGV <https://igv.org/>`__ 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 <example_usage>` like :ref:`BAM`, :ref:`bigWig`, :ref:`BED` and :ref:`bedGraph` format.
+
+We recommend downloading the `desktop version of IGV <https://igv.org/doc/desktop/#DownloadPage/>`__, 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 <https://igv.org/doc/desktop/#QuickStart/>`__ 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 <https://igv.org/doc/desktop/#FileFormats/DataTracks/#bam>`__.
+
+   This is of no relevance if you're :ref:`using IGV from Galaxy <galaxy-visualize>` since Galaxy will handle the index file transparently for you.
+
+
+