annotate computeGCBias.xml @ 0:4409903dcb88 draft

planemo upload for repository https://github.com/fidelram/deepTools/tree/master/galaxy/wrapper/ commit 0a9265a12a303b54cdaa974e82e87c2ac60962ee-dirty

<tool id="deeptools_compute_gc_bias" name="computeGCBias" version="@WRAPPER_VERSION@.0">
    <description>to see whether your samples should be normalized for GC bias</description>
    <macros>
        <token name="@BINARY@">computeGCBias</token>
        <import>deepTools_macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <command>
<![CDATA[
        ln -s "$bamInput" "local_bamInput.bam" &&
        ln -s "$bamInput.metadata.bam_index" local_bamInput.bam.bai &&

        @BINARY@
            @THREADS@
            --bamfile local_bamInput.bam
            --GCbiasFrequenciesFile $outFileName
            --fragmentLength $fragmentLength

            @reference_genome_source@

            #if $effectiveGenomeSize.effectiveGenomeSize_opt == "specific":
                --effectiveGenomeSize $effectiveGenomeSize.effectiveGenomeSize
            #else:
                --effectiveGenomeSize $effectiveGenomeSize.effectiveGenomeSize_opt
            #end if

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

            #if $advancedOpt.showAdvancedOpt == "yes":
                --sampleSize '$advancedOpt.sampleSize'
                --regionSize '$advancedOpt.regionSize'

                #if $advancedOpt.filterOut:
                    --filterOut $advancedOpt.filterOut
                #end if

                #if $advancedOpt.extraSampling:
                    --extraSampling $advancedOpt.extraSampling
                #end if
            #end if

            #if str($image_format) != 'none':
                --biasPlot $outImageName
                --plotFileFormat $image_format
            #end if
]]>
    </command>
    <inputs>
        <param name="bamInput" format="bam" type="data" label="BAM file"
            help="The BAM file must be sorted."/>

        <expand macro="reference_genome_source" />
        <expand macro="effectiveGenomeSize" />
        <expand macro="fragmentLength" />
        <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 name="sampleSize" type="integer" value="50000000" min="1"
                    label="Number of sampling points to consider" help="(--sampleSize)" />
                <param name="regionSize" type="integer" value="300" min="1"
                    label="Region size"
                    help ="To plot the reads per GC over a region, the size of the region is
                    required (see below for more details about the method). By default, the bin size
                    is set to 300 bases, which is close to the standard fragment size of many sequencing
                    applications. However, if the depth of sequencing is low, a larger bin size will
                    be required, otherwise many bins will not overlap with any read. (--regionSize)"/>
                <param name="filterOut" type="data" format="bed" optional="true"
                    label="BED file containing genomic regions to be excluded from the estimation of the correction"
                    help="Such regions usually contain repetitive regions and peaks that, if included, would
                    bias the correction. It is recommended to filter out known repetitive regions if multi-reads
                    (reads that map to more than one genomic position) were excluded. In the case of ChIP-seq data,
                    it is recommended to first use a peak caller to identify and filter out the identified peaks. (--filterOut)" />
                <param name="extraSampling" type="data" format="bed" optional="true"
                    label="BED file containing genomic regions for which extra sampling is required because they are underrepresented in the genome"
                    help="(--extraSampling)" />
            </when>
        </conditional>
        <param name="image_format" type="select"
            label="GC bias plot"
            help="If given, a diagnostic image summarizing the GC bias found on the sample will be created. (--plotFileFormat)">
            <option value="none">No image</option>
            <option value="png" selected="true">Image in png format</option>
            <option value="pdf">Image in pdf format</option>
            <option value="svg">Image in svg format</option>
            <option value="eps">Image in eps format</option>
        </param>
    </inputs>
    <outputs>
        <data name="outFileName" format="tabular" />
        <data name="outImageName" format="png" label="${tool.name} GC-bias Plot">
            <filter>
            ((
                image_format != 'none'
            ))
            </filter>
            <change_format>
                <when input="image_format" value="pdf" format="pdf" />
                <when input="image_format" value="svg" format="svg" />
                <when input="image_format" value="eps" format="eps" />
            </change_format>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="bamInput" value="paired_chr2L.bam" ftype="bam" />
            <param name="image_format" value="png" />
            <param name="showAdvancedOpt" value="yes" />
            <param name="regionSize" value="1" />
            <param name="ref_source" value="history" />
            <param name="input1" value="sequence.2bit" />
            <param name="sampleSize" value="10" />
            <param name="effectiveGenomeSize_opt" value="specific" />
            <param name="effectiveGenomeSize" value="23011544" />
            <param name="region" value="chr2L" />
            <param name="image_format" value="none" />
            <output name="outFileName" file="computeGCBias_result1.tabular" ftype="tabular" />
        </test>
    </tests>
    <help>
<![CDATA[
**What it does**

This tool computes the GC bias using the method proposed in Benjamini and Speed (2012) Nucleic Acids Res. (see below for further details).
The output is used to plot the bias and can also be used later on to correct the bias with the tool correctGCbias.
There are two plots produced by the tool: a boxplot showing the absolute read numbers per GC-content bin and an x-y plot
depicting the ratio of observed/expected reads per GC-content bin.

-----

**Summary of the method used**

In order to estimate how many reads with what kind of GC content one should have sequenced, we first need to determine how many regions the 
reference genome contains with each percentage of GC content, i.e. how many regions in the genome have 50% GC (or 10% GC or 90% GC or...).
We then sample a large number of equally sized genomic bins and count how many times we see a bin with 50% GC (or 10% GC or 90% or...). These EXPECTED values are independent of any
sequencing bias and is purely dependent on the underlying genome (i.e. it will most likely vary between mouse and fruit fly due to their genome's different GC contents).
The OBSERVED values are based on the reads from the sequenced sample. Instead of noting how many genomic regions there are per GC content, we now count the reads per GC content.
In an ideal sample without GC bias, the ratio of OBSERVED/EXPECTED values should be close to 1 regardless of the GC content. Due to PCR (over)amplifications, the majority of ChIP samples
usually shows a significant bias towards reads with high GC content (>50%)

.. image:: $PATH_TO_IMAGES/QC_GCplots_input.png


You can find more details on the computeGCBias doc page: https://deeptools.readthedocs.org/en/master/content/tools/computeGCBias.html


**Output files**:

- Diagnostic plot

  - box plot of absolute read numbers per GC-content bin
  - x-y plot of observed/expected read ratios per GC-content bin

- Data matrix

  - to be used for GC correction with correctGCbias


-----

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