annotate fgbio_call_molecular_consensus_reads.xml @ 2:d469e546604b draft default tip

"planemo upload commit 77a5370a0978b5332bb3a9f063588a52a468ea08"

<tool id="fgbio_call_molecular_consensus_reads" name="fgbio CallMolecularConsensusReads" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" python_template_version="3.5">
    <description>Calls consensus sequences from reads with the same unique molecular tag</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <version_command>fgbio --version</version_command>
    <command detect_errors="exit_code"><![CDATA[
        fgbio CallMolecularConsensusReads
        --input '$input'
        --min-reads=$min_reads
        --output '$output'
        ## optional settings
        #if $filter_options.max_reads:
            --max-reads=$filter_options.max_reads
        #end if
        #if $filter_options.error_rate_pre_umi
            --error-rate-pre-umi=$filter_options.error_rate_pre_umi
        #end if
        #if $filter_options.error_rate_post_umi
            --error-rate-post-umi=$filter_options.error_rate_post_umi
        #end if
        #if $filter_options.min_input_base_quality
            --min-input-base-quality=$filter_options.min_input_base_quality
        #end if

        #if $bam_options.read_name_prefix
            --read-name-prefix='$bam_options.read_name_prefix'
        #end if
        #if $bam_options.tag
            --tag=$bam_options.tag
        #end if
        #if $bam_options.read_group_id
            --read-group-id=$bam_options.read_group_id
        #end if
        #if $bam_options.output_per_base_tags
            --output-per-base-tags=$bam_options.output_per_base_tags
        #end if
        #if $output_rejects
            --rejects='$rejects'
        #end if
    ]]></command>
    <inputs>
        <param name="input" type="data" format="unsorted.bam,bam" label="BAM TemplateCoorinate sorted by fgbio SortBAM"/>
        <param argument="--min-reads" type="integer" value="" min="1" label="Minimum number of reads to produce a consensus base" help="Default: 1"/>
        <section name="filter_options" title="Optional Filter Settings" expanded="false">
            <param argument="--max-reads" type="integer" value="" min="1" optional="true" label="Maximum number of reads to to use when building a consensus" 
                   help="If more than this many reads are present in a tag family, the family is randomly downsampled to exactly max-reads reads."/>
            <param argument="--error-rate-pre-umi" type="integer" value="" min="1" optional="true" label="Phred-scaled error rate for an error prior to the UMIs being integrated" help="Default: 45"/>
            <param argument="--error-rate-post-umi" type="integer" value="" min="1" optional="true" label="Phred-scaled error rate for an error post the UMIs being integrated" help="Default: 40"/>
            <param argument="--min-input-base-quality" type="integer" value="" min="1" optional="true" label="Ignore bases in raw reads that have Q below this value" help="Default: 10"/>
        </section>
        <section name="bam_options" title="BAM Settings" expanded="false">
            <param argument="--read-name-prefix" type="text" value="" optional="true" label="Prefix for all consensus read names"/> 
            <param argument="--tag" type="text" value="" optional="true" label="The SAM attribute with the unique molecule tag" help="Default: MI"> 
                <expand macro="sam_tag_validator"/>
            </param>
            <param argument="--read-group-id" type="text" value="" optional="true" label="The new read group ID for all the consensus reads" help="Default: A"/>
            <param argument="--output-per-base-tags" type="select" value="" optional="true" label="Produce tags on consensus reads that contain per-base information">
                <option value="true">Yes</option>
                <option value="flse">Yes</option>
            </param>
        </section>
        <expand macro="sam_sort_order" />
        <param argument="output_rejects" type="boolean" truevalue="true" falsevalue="false" checked="false" label="Output BAM of rejected reads"/>
    </inputs>
    <outputs>
        <data name="rejects" format="unsorted.bam" >
            <filter>output_rejects == True</filter>
            <expand macro="sort_order_change_format" />
        </data>
        <data name="output" format="unsorted.bam" >
            <expand macro="sort_order_change_format" />
        </data>
    </outputs>
    <help><![CDATA[
**fgbio CallMolecularConsensusReads**

Calls consensus sequences from reads with the same unique molecular tag.

Reads with the same unique molecular tag are examined base-by-base to assess the likelihood of each base in the source molecule. The likelihood model is as follows:

  1. First, the base qualities are adjusted. The base qualities are assumed to represent the probability of a sequencing error (i.e. the sequencer observed the wrong base present on the cluster/flowcell/well). The base quality scores are converted to probabilities incorporating a probability representing the chance of an error from the time the unique molecular tags were integrated to just prior to sequencing. The resulting probability is the error rate of all processes from right after integrating the molecular tag through to the end of sequencing.

  2. Next, a consensus sequence is called for all reads with the same unique molecular tag base-by-base. For a given base position in the reads, the likelihoods that an A, C, G, or T is the base for the underlying source molecule respectively are computed by multiplying the likelihood of each read observing the base position being considered. The probability of error (from 1.) is used when the observed base does not match the hypothesized base for the underlying source molecule, while one minus that probability is used otherwise. The computed likelihoods are normalized by dividing them by the sum of all four likelihoods to produce a posterior probability, namely the probability that the source molecule was an A, C, G, or T from just after integrating molecular tag through to sequencing, given the observations. The base with the maximum posterior probability as the consensus call, and the posterior probability is used as its raw base quality.  

  3. Finally, the consensus raw base quality is modified by incorporating the probability of an error prior to integrating the unique molecular tags. Therefore, the probability used for the final consensus base quality is the posterior probability of the source molecule having the consensus base given the observed reads with the same molecular tag, all the way from sample extraction and through sample and library preparation, through preparing the library for sequencing (e.g. amplification, target selection), and finally, through sequencing.  This tool assumes that reads with the same tag are grouped together (consecutive in the file). Also, this tool calls each end of a pair independently, and does not jointly call bases that overlap within a pair. Insertion or deletion errors in the reads are not considered in the consensus model.

Particular attention should be paid to setting the --min-reads parameter as this can have a dramatic effect on both results and runtime. For libraries with low duplication rates (e.g. 100-300X exomes libraries) in which it is desirable to retain singleton reads while making consensus reads from sets of duplicates, --min-reads=1 is appropriate. For libraries with high duplication rates where it is desirable to only produce consensus reads supported by 2+ reads to allow error correction, --min-reads=2 or higher is appropriate. After generation, consensus reads can be further filtered using the FilterConsensusReads tool. As such it is always safe to run with --min-reads=1 and filter later, but filtering at this step can improve performance significantly.


Consensus reads have a number of additional optional tags set in the resulting BAM file. The tags break down into those that are single-valued per read:

  - consensus depth      [cD] (int)  : the maximum depth of raw reads at any point in the consensus read
  - consensus min depth  [cM] (int)  : the minimum depth of raw reads at any point in the consensus read
  - consensus error rate [cE] (float): the fraction of bases in raw reads disagreeing with the final consensus calls

And those that have a value per base:

  - consensus depth  [cd] (short[]): the count of bases contributing to the consensus read at each position
  - consensus errors [ce] (short[]): the number of bases from raw reads disagreeing with the final consensus base

The per base depths and errors are both capped at 32,767. In all cases no-calls (Ns) and bases below the --min-input-base-quality are not counted in tag value calculations.

http://fulcrumgenomics.github.io/fgbio/tools/latest/CallMolecularConsensusReads.html
    ]]></help>
    <expand macro="citations" />
</tool>