<?xml version="1.0"?>
<tool id="telescope_assign" name="Reassign reads" version="@VERSION@">
    <description>with TELESCOPE using a statistical model</description>
    <macros>
        <token name="@VERSION@">1.0.3</token>
    </macros>
    <requirements>
        <requirement type="package" version="@VERSION@">telescope</requirement>
        <requirement type="package" version="1.9">samtools</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        mkdir tempdir &&
        mkdir outdir &&
        telescope assign '$input_alignment' '$input_gtf'
            --tempdir tempdir
            --outdir outdir
            --ncpu \${GALAXY_SLOTS:-1}
            $updated_sam
            #if str($advanced.advanced_options) == 'select':
                --reassign_mode $advanced.reassign_mode
                --conf_prob $advanced.conf_prob
                --overlap_mode $advanced.overlap_mode
                --overlap_threshold $advanced.overlap_threshold
                --annotation_class $advanced.annotation_class
                --pi_prior $advanced.pi_prior
                --theta_prior $advanced.theta_prior
                --em_epsilon $advanced.em_epsilon
                --max_iter $advanced.max_iter
                $advanced.use_likelihood
            #end if
        #if $updated_sam
            &&
            if [ -f outdir/telescope-updated.bam ] ; then
                samtools sort outdir/telescope-updated.bam > '$updated_alignment' ;
            else
                echo 'Updated alignment file not found.' ;
                exit 1 ;
            fi
        #end if
    ]]></command>
    <inputs>
        <param name="input_alignment" type="data" format="sam,bam" label="Input SAM or BAM file" />
        <param name="input_gtf" type="data" format="gtf" label="Input annotation" />
        <param argument="--updated_sam" type="boolean" truevalue="--updated_sam" falsevalue="" label="Also output an updated BAM file with reassigned reads" />
        <conditional name="advanced">
            <param name="advanced_options" type="select" label="Advanced options">
                <option value="defaults">Use defaults</option>
                <option value="select">Select values</option>
            </param>
            <when value="defaults" />
            <when value="select">
                <param argument="--reassign_mode" type="select" label="Reassignment mode"
                    help="After EM is complete, each fragment is reassigned according to the expected value of its membership weights. The reassignment method is the method for resolving the &quot;best&quot; reassignment for fragments that have multiple possible reassignments. Available modes are: &quot;exclude&quot; - fragments with multiple best assignments are excluded from the final counts; &quot;choose&quot; - the best assignment is randomly chosen from among the set of best assignments; &quot;average&quot; - the fragment is divided evenly among the best assignments; &quot;conf&quot; - only assignments that exceed a certain threshold (see --conf_prob) are accepted; &quot;unique&quot; - only uniquely aligned reads are included. NOTE: Results using all assignment modes are included in the Telescope report by default. This argument determines what mode will be used for the &quot;final counts&quot; column. (default: exclude)">
                    <option value="exclude">Exclude</option>
                    <option value="choose">Choose</option>
                    <option value="average">Average</option>
                    <option value="conf">Conf</option>
                    <option value="unique">Unique</option>
                </param>
                <param argument="--conf_prob" type="float" value="0.9" min="0" max="1" label="Minimum probability for high confidence assignment" />
                <param argument="--overlap_mode" type="select" label="Overlap mode" help="The method used to determine whether a fragment overlaps feature">
                    <option value="threshold">Threshold</option>
                    <option value="intersection-strict">Strict intersection</option>
                    <option value="union">Union</option>
                </param>
                <param argument="--overlap_threshold" type="float" value="0.2" min="0" max="1" label="Fraction of fragment that must be contained within a feature to be assigned to that locus" help="Ignored unless overlap mode is 'threshold'" />
                <param argument="--annotation_class" type="select" label="Annotation class" help="Both htseq and intervaltree appear to yield identical results. Performance differences are TBD.">
                    <option value="intervaltree">Interval tree</option>
                    <option value="htseq">HTSeq</option>
                </param>
                <param argument="--pi_prior" type="integer" value="0" label="Prior on &#960;" help="Equivalent to adding n unique reads." />
                <param argument="--theta_prior" type="integer" value="0" label="Prior on &#952;" help="Equivalent to adding n non-unique reads." />
                <param argument="--em_epsilon" type="float" value="0.0000001" label="EM Algorithm &#965; cutoff" help="Default: 1e-7" />
                <param argument="--max_iter" type="integer" value="100" label="EM Algorithm maximum iterations" help="Default: 100" />
                <param argument="--use_likelihood" type="boolean" truevalue="--use_likelihood" falsevalue="" label="Use difference in log-likelihood as convergence criteria" />
            </when>
        </conditional>
    </inputs>
    <outputs>
        <data name="output" format="tabular" from_work_dir="outdir/telescope-telescope_report.tsv" />
        <data name="updated_alignment" format="bam">
            <filter>updated_sam</filter>
        </data>
    </outputs>
    <tests>
        <test>
            <param name="input_alignment" value="telescope-in1.bam" />
            <param name="input_gtf" value="telescope-in1.gtf" />
            <param name="updated_sam" value="true" />
            <output name="output" file="telescope-out1.tabular" />
            <output name="updated_alignment" file="telescope-out1.bam" />
        </test>
    </tests>
    <help><![CDATA[
Output
------

Telescope has two main output files: the telescope report and an updated
SAM file (optional). The report file is most important for downstream
differential expression analysis since it contains the fragment count
estimates. The updated SAM file is useful for downstream locus-specific
analyses.

Telescope report
~~~~~~~~~~~~~~~~

The first line in the telescope report is a comment (starting with a
“#”) that contains information about the run such as the number of
fragments processed, number of mapped fragments, number of uniquely and
ambiguously mapped fragments, and number of fragments mapping to the
annotation. The total number of mapped fragments may be useful for
normalization.

The rest of the report is a table with calculated expression values for
individual transposable element locations. The columns of the table are:

-  ``transcript`` - Transcript ID, by default from "locus" field. See
   --attribute argument to use a different attribute.
-  ``transcript_length`` - Approximate length of transcript. This is
   calculated from the annotation, not the data, and is equal to the
   spanning length of the annotation minus any non-model regions.
-  ``final_count`` - Total number of fragments assigned to transcript
   after fitting the Telescope model. This is the column to use for
   downstream analysis that models data as negative binomial, i.e.
   DESeq2.
-  ``final_conf`` - Final confident fragments. The number of fragments
   assigned to transcript whose posterior probability exceeds a cutoff,
   0.9 by default. Set this using the --conf_prob argument.
-  ``final_prop`` - Final proportion of fragments represented by
   transcript. This is the final estimate of the π parameter.
-  ``init_aligned`` - Initial number of fragments aligned to transcript.
   A given fragment will contribute +1 to each transcript that it is
   aligned to, thus the sum of this will be greater than the number of
   fragments if there are multimapped reads.
-  ``unique_count`` - Unique count. Number of fragments aligning
   uniquely to this transcript.
-  ``init_best`` - Initial number of fragments aligned to transcript
   that have the "best" alignment score for that fragment. Fragments
   that have the same best alignment score to multiple transcripts will
   contribute +1 to each transcript.
-  ``init_best_random`` - Initial number of fragments aligned to
   transcript that have the "best" alignment score for that fragment.
   Fragments that have the same best alignment score to multiple
   transcripts will be randomly assigned to one transcript.

Updated BAM file
~~~~~~~~~~~~~~~~

The updated BAM file contains those fragments that has at least 1
initial alignment to a transposable element. The final assignment and
probabilities are encoded in the SAM tags:

-  ``ZF:Z`` Assigned Feature - The name of the feature that alignment is
   assigned to.
-  ``ZT:Z`` Telescope tag - A value of ``PRI`` indicates that this
   alignment is the best hit for the feature and is used in the
   likelihood calculations. Otherwise the value will be ``SEC``, meaning
   that another alignment to the same feature has a higher score.
-  ``ZB:Z`` Best Feature = The name(s) of the highest scoring feature(s)
   for the fragment.
-  ``YC:Z`` Specifies color for alignment as R,G,B. UCSC sanctioned tag,
   see documentation `here.`_
-  ``XP:Z`` Alignment probability - estimated posterior probability for
   this alignment.

.. _here.: http://genome.ucsc.edu/goldenpath/help/hgBamTrackHelp.html

    ]]>
    </help>
    <citations>
        <citation type="doi">10.1101/398172</citation>
    </citations>
</tool>