annotate mmquant.xml @ 1:87c5fa8651c1 draft

planemo upload commit fb76aa0a938a2498d3206e6039bc1d9906e6c2ce-dirty

<tool id="mmquant" name="Gene quantification (mmquant)" version="0.1.0">
    <requirements>
        <requirement type="package" version="0.1.0">mmquant</requirement>
    </requirements>
    <stdio>
        <exit_code range="1:" />
    </stdio>
	<command><![CDATA[
        mmquant
			-a "$annotation"
			-r
			#for $r in $reads_info
				${r.reads.file_name}
			#end for
			-f
			#for $r in $reads_info
				${r.reads.ext}
			#end for
			-s
			#for $r in $reads_info
				${r.strand}
			#end for
			-n
			#for $r in $reads_info
				${r.name}
			#end for
			-l "$overlap"
			"$gene_name"
			-c "$count"
			-m "$merge"
			-o "$output"
			-d "$n_overlap"
			-D "$pc_overlap"
    ]]></command>
    <inputs>
        <param name="annotation" type="data" label="Annotation" format="gtf" />
		<repeat name="reads_info" title="Reads" min="1" default="1">
			<param name="reads"  type="data"   label="Reads"  multiple="false" format="sam,bam" />
			<param name="name"   type="text"   label="Sample name" value="sample_N" />
			<param name="strand" type="select" label="Strand" multiple="false" >
				<option value="U" selected="yes">unknown</option>
				<option value="FR">forward-reverse (for paired-end reads)</option>
				<option value="RF">reverse-forward (for paired-end reads)</option>
				<option value="F">forward (for single-end reads)</option>
				<option value="R">reverse (for single-end reads)</option>
			</param>
		</repeat>
		<param name="overlap" type="float" value="-1" label="Overlap type" help="&lt;0: read is included, &lt;1: overlap, otherwise: # nt" />
        <param name="gene_name" type="boolean" label="Print gene name instead of IDs" truevalue="-g" falsevalue="" help="use gene name instead of gene ID in the output file" />
		<param name="count" type="integer" value="0" min="0" label="Count threshold" help="Do not display genes with less than N reads" />
		<param name="merge" type="float" value="0.0" min="0.0" max="1.0" label="Merge threshold" help="Merge gene aggregate count with parent aggregate if count is low" />
		<param name="n_overlap" type="integer" value="30" min="1" label="Difference of overlapping" help="Number of overlapping bp between the best matches and the other matches" />
		<param name="pc_overlap" type="float" value="0.5" min="0.0" max="1.0" label="Ratio of overlapping" help="Ratio of overlapping bp between the best matches and the other matches" />
    </inputs>
    <outputs>
        <data name="output" format="txt" label="${tool.name} on ${on_string}" />
    </outputs>
    <tests>
        <test>
            <param name="annotation" value="test_mmquant_1.gtf" />
            <param name="reads" value="test_mmquant_1.sam" />
            <param name="name" value="test" />
            <param name="strand" value="U" />
            <output name="output" file="test_mmquant_1.txt" ftype="txt" />
        </test>
    </tests>
	<help>
**Why using this tool?**

This tool counts the number of reads (produced by RNA-Seq) per gene, much like HTSeq-count_ and featureCounts_.  The main difference with other tools is that multi-mapping reads are counted differently: if a read is mapped to gene A, gene B, and gene C, the tool will create a new feature, "geneA--geneB--geneC", that will be counted once.

.. _HTSeq-count: http://www-huber.embl.de/users/anders/HTSeq/doc/overview.html
.. _featureCounts: http://bioinf.wehi.edu.au/featureCounts/

**Why it matters?**

Recently, an article_ showed that RNA-Seq quantification tools are not accurate, leading to errors while finding differentially expressed genes.  The authors suggest this method, that may not provide the genes that are differentially expressed (something that RNA-Seq alone cannot do), but the groups of genes that are differentially expressed.

.. _article: http://www.genomebiology.com/2015/16/1/177

**Strands**

Strands can be:

* for paired-end reads: ``U`` (unknown), ``FR`` (forward-reverse), ``RF`` (reverse-forward), ``FF`` (forward-forward);

* for single-end reads: ``U`` (unknown), ``F`` (forward), ``R`` (reverse);

* Default: ``U``.


**Annotation file**

The annotation file should be in GTF.  GFF might work too.  The tool only uses the gene/transcript/exon types.


**Reads files**

The reads should be given in SAM or BAM format, and be sorted (by position).  The reads can be single end or paired-end (or a mixture thereof).

You can use the samtools_ to sort them.  This tool uses the NH flag (provides the number of hits for each read, see the specification_), so be sure that your mapping tool sets it adequately (yes, TopHat2_ and STAR_ do it fine).  You should also check how your mapping tool handles multi-mapping reads (this can usually be tuned using the appropriate parameters).

.. _samtools: http://www.htslib.org/
.. _specification: https://samtools.github.io/hts-specs/SAMv1.pdf
.. _TopHat2: http://ccb.jhu.edu/software/tophat/index.shtml
.. _STAR: https://github.com/alexdobin/STAR/releases

**Read mapping to several genes**

We will suppose here that the ``-l 1`` strategy is used (i.e. a read is attributed to a gene as soon as at least 1 nucleotide overlap). The example can be extended to other strategies as well.

If a read (say, of size 100), maps unambiguously and overlaps with gene A and B, it will be counted as 1 for the new "gene" gene_A--gene_B. However, suppose that only 1 nucleotide overlaps with gene A, whereas 100 nucleotides overlap with gene B (yes, genes A and B overlap). You probably would like to attribute the read to gene B.

The options ``Difference of overlapping`` and ``Ratio of overlapping`` control this. We compute the number of overlapping nucleotides between a read and the overlapping genes. If a read overlaps "significantly" more with one gene than with all the other genes, they will attribute the read to the former gene only.

The option ``Difference of overlapping`` *n* computes the differences of overlapping nucleotides. Let us name *N_A* and *N_B* the number of overlapping nucleotides with genes A and B respectively. If *N_A >= N_B + n*, then the read will be attributed to gene A only.

The option ``Ratio of overlapping`` *m* compares the ratio of overlapping nucleotides. If *N_A / N_B >= m*, then the read will be attributed to gene A only.

If both option ``Difference of overlapping`` *n* and ``Ratio of overlapping`` *m* are used, then the read will be attributed to gene A only iff both *N_A >= N_B + n* and *N_A / N_B >= m*.


**Output file**

The output is a tab-separated file, to be use in EdgeR or DESeq, for instance.  If the user provided *n* reads files, the output will contain *n+1* columns:

============== ======== ======== ===
Gene           sample_1 sample_2 ...
============== ======== ======== ===
gene_A         ...      ...      ...
gene_B         ...      ...      ...
gene_B--gene_C ...      ...      ...
============== ======== ======== ===

The first line is the ID of the genes.
If a read maps several genes (say, gene_B and gene_C), a new feature is added to the table, gene_B--gene_C.  The reads that can be mapped to these genes will be counted there (but not in the gene_B nor gene_C lines).

With the ``Print names`` option, the gene names are used instead of gene IDs.  If two different genes have the same name, the systematic name is added, like: ``Mat2a (ENSMUSG00000053907)``.

Note that the gene IDs and gene names should be given in the GTF file after the ``gene_id`` and ``gene_name`` tags respectively.

**Output stats**

The output stats are given in standard error.

The general shape is::

    Results for sample_A:
        # hits:                     N
        # uniquely mapped reads:    N (x%)
        # ambiguous hits:           N (x%)
        # non-uniquely mapped hits: N (x%)
        # unassigned hits:          N (x%)

These figures mainly provide stats on hits; one sequence may have zero, one, or several hits.  An ambiguous hit is a hit that overlaps several annotation features.  A non-uniquely mapped hit belongs to a sequence that maps several loci in the genome.

**Overlap**

The way a read R is mapped to a gene A depends on the overlap *n* value:

==================== ===============================================
if *n* is            then R is mapped to A iff
==================== ===============================================
a negative value     R is included in A
a positive integer   they have at least *n* nucleotides in common
a float value (0, 1) *n* % of the nucleotides of R are shared with A
==================== ===============================================

**Merge Threshold**

Sometimes, there are very few reads that can be mapped unambiguously to a gene A, because it is very similar to gene B.

============== ==========
Gene           sample_1 
============== ==========
gene_A         *x*      
gene_B         *y*      
gene_A--gene_B *z*      
============== ==========

In the previous example, suppose that *x &lt;&lt; z*.  In this case, you can move all the reads from gene_A to gene_A--gene_B, using the merge threshold *t*, a float in (0, 1).  If *x &lt; t* x *y*, then the reads are transferred.

**Count Threshold**

If the maximum number of reads for a gene is less than the count threshold (a non-negative integer), then the corresponding line is discarded.


**Contact**

Comment? Suggestion? Do not hesitate sending me an email_.

.. _email: mailto:[e-mail]
    </help>
    <citations>
        <citation type="bibtex">
@misc{bitbucketmmquant,
  author    = {Zytnicki.},
  year      = {2016},
  title     = {multi-mapping-counter},
  publisher = {BitBucket},
  journal   = {BitBucket repository},
  url       = {https://bitbucket.org/mzytnicki/multi-mapping-counter},
}</citation>
    </citations>
</tool>