annotate plotFingerprint.xml @ 30:4ed32329e0ed draft default tip

planemo upload for repository https://github.com/deeptools/deepTools/tree/master/galaxy/wrapper/ commit 4a4029b5c2e725b7cebc27217b76d23910508412

<tool id="deeptools_plot_fingerprint" name="plotFingerprint" version="@TOOL_VERSION@+galaxy0" profile="@GALAXY_VERSION@">
    <description>plots profiles of BAM files; useful for assessing ChIP signal strength</description>
    <macros>
        <token name="@BINARY@">plotFingerprint</token>
        <import>deepTools_macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command>
<![CDATA[
        @multiple_input_bams@
        @BINARY@
            @THREADS@
            --bamfiles #echo " ".join($files)
            --labels #echo " ".join($labels)
            --plotFile $outFileName

            #if $output.showOutputSettings == "yes"
                --plotFileFormat $output.outFileFormat
                #if $output.saveRawCounts:
                    --outRawCounts '$outFileRawCounts'
                #end if
                #if $output.saveQualityMetrics:
                    --outQualityMetrics '$outFileQualityMetrics'
                    #if $output.JSDsample:
                        #if "'{}'".format($output.JSDsample.display_name) in $labels:
                            #set JSDidx = $labels.index("'{}'".format($output.JSDsample.display_name))
                            --JSDsample '${JSDidx}.bam'
                        #end if
                    #end if
                #end if
            #else
                --plotFileFormat 'png'
            #end if

            #if str($region).strip() != '':
                --region '$region'
            #end if

            #if $advancedOpt.showAdvancedOpt == "yes":
                --binSize '$advancedOpt.binSize'
                --numberOfSamples '$advancedOpt.numberOfSamples'

                $advancedOpt.ignoreDuplicates
                $advancedOpt.skipZeros

                #if $advancedOpt.plotTitle and str($advancedOpt.plotTitle.value) != "":
                    --plotTitle '$advancedOpt.plotTitle'
                #end if
                @ADVANCED_OPTS_READ_PROCESSING@
                @blacklist@
            #end if
]]>
    </command>

    <inputs>
        <expand macro="multiple_input_bams" MIN="1"/>
        <expand macro="custom_sample_labels" />
        <expand macro="region_limit_operation" />

        <conditional name="advancedOpt">
            <param name="showAdvancedOpt" type="select" label="Show advanced options" >
                <option value="no" selected="true">no</option>
                <option value="yes">yes</option>
            </param>
            <when value="no" />
            <when value="yes">
                <param argument="--binSize" type="integer" value="500" min="1"
                   label="Bin size in bases"
                   help="Length in bases for a window used to sample the genome."/>
                <param argument="--numberOfSamples" type="integer" value="100000" min="1"
                   label="Number of samples"
                   help="Number of samples taken from the genome to compute the scaling factors."/>
                <expand macro="read_processing_options" />
                <expand macro="skipZeros" />
                <expand macro="plotTitle" />
                <expand macro="blacklist" />
            </when>
        </conditional>

        <conditional name="output">
            <param name="showOutputSettings" type="select" label="Show advanced output settings">
                <option value="no" selected="true">no</option>
                <option value="yes">yes</option>
            </param>
            <when value="no" />
            <when value="yes">
                <expand macro="input_image_file_format" />
                <param name="saveRawCounts" type="boolean" label="Save the bin counts" help="(--outRawCounts)"/>
                <param name="saveQualityMetrics" type="boolean" label="Save quality metrics"
                   help="The file will have one row per input BAM file and columns containing a variety of QC metrics. For the full description of all metrics and their interpretation, please see our online documentation: http://deeptools.readthedocs.io/en/latest/content/feature/plotFingerprint_QC_metrics.html. (--outQualityMetrics)"/>
                <param name="JSDsample" type="data" format="bam" optional="true"
                   label="Jensen-Shannon distance reference sample"
                   help="If output metrics should be saved, then use this sample as the reference for computing the Jensen-Shannon distance and CHANCE metrics of all other samples. Normally this is an input sample. If you don't specify this, then these metrics will not be computed. This is only applicable if quality metrics are being saved. (--JSDsample)" />
            </when>
        </conditional>
    </inputs>
    <outputs>
        <expand macro="output_image_file_format" />
        <data format="tabular" name="outFileRawCounts" label="${tool.name} on ${on_string}: bin counts">
            <filter>
            ((
                output['showOutputSettings'] == 'yes' and
                output['saveRawCounts'] is True
            ))
            </filter>
        </data>
        <data format="tabular" name="outFileQualityMetrics" label="${tool.name} on ${on_string}: quality metrics">
            <filter>
            ((
                output['showOutputSettings'] == 'yes' and
                output['saveQualityMetrics'] is True
            ))
            </filter>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="bamfiles" value="bowtie2 test1.bam,bowtie2 test1.bam" ftype="bam" />
            <param name="showAdvancedOpt" value="no" />
            <param name="showOutputSettings" value="no" />
            <output name="outFileName" file="plotFingerprint_result1.png" ftype="png" compare="sim_size" />
        </test>
        <test>
            <param name="bamfiles" value="bowtie2 test1.bam,bowtie2 test1.bam" ftype="bam" />
            <param name="showAdvancedOpt" value="yes" />
            <param name="showOutputSettings" value="yes" />
            <param name="saveRawCounts" value="True" />
            <param name="saveQualityMetrics" value="True" />
            <param name="plotTitle" value="Test Fingerprint Plot" />
            <param name="JSDsample" value="bowtie2 test1.bam" ftype="bam" />
            <output name="outFileName" file="plotFingerprint_result2.png" ftype="png" compare="sim_size" />
            <output name="outFileRawCounts" file="plotFingerprint_result2.tabular" ftype="tabular" />
            <output name="outFileQualityMetrics" file="plotFingerprint_quality_metrics.tabular" ftype="tabular" />
        </test>
    </tests>
    <help>
<![CDATA[


What it does
------------

This tool is useful for assessing the strength of a ChIP (i.e. how clearly the enrichment signal can be separated from the background)
and is based on a method described in Diaz et al. (2012) Stat Appl Genet Mol Biol 11(3).


Output
------

The default output is a diagnostic plot (see below for an example and further down for some background information).

Optionally, you can obtain the table of raw values that were used to generate the plot.

.. image:: $PATH_TO_IMAGES/plotFingerprint_output.png
  :width: 600
  :height: 395


Example plot
-------------

What follows is the output of ``plotFingerprint`` with our test ChIP-Seq data sets, limiting the analysis to chromosome X. Single-end reads were extended to
200 bp (advanced options).

.. image:: $PATH_TO_IMAGES/bamFP_galaxy_output.png
   :width: 600
   :height: 450

-----

Theoretical Background
----------------------

The tool first samples indexed BAM files and sums the per-base coverage of reads/fragments overlapping a window (bin) of the specified length.
These values are then sorted according to their rank (the bin with the highest number of reads has the highest rank)
and the cumulative sum plotted. An ideal input (control) with a uniform distribution of reads alignments
and infinite sequencing depth will result in a diagonal line. A very specific and strong ChIP enrichment, on the other hand, would result in a large portion
of reads accumulating in just a few bins and the resulting plot showing a steep rise toward the right-most edge. Such results are
most commonly seen with transcription factors.


.. image:: $PATH_TO_IMAGES/QC_fingerprint.png
   :width: 600
   :height: 294

-----

@REFERENCES@
]]>
    </help>
    <expand macro="citations" />
</tool>