<tool id="ribotaper_create_metaplots" name="ribotaper part 2: metagene analysis for P-sites definition" version="0.1.0">
    <requirements>
            <requirement type="package" version="1.3.1">ribotaper</requirement>
    </requirements>
    <stdio>
        <exit_code range="1:" />
    </stdio>

    <command><![CDATA[
        create_metaplots.bash
            "$ribo_bam"
            "$start_stops_FAR"
            "metagene"

        &&

        find "metaplots"
            "-name"
            "metagene*.pdf"
            | sort | xargs gs
            "-dAutoRotatePages=/None"
            "-dBATCH"
            "-dNOPAUSE"
            "-q"
            "-sDEVICE=pdfwrite"
            "-sOutputFile=merged_metagene.pdf"

    ]]></command>
    <inputs>
        <param name="ribo_bam" type="data" format="bam" label="ribo_bam" help="Ribo-seq alignment file in BAM format."/>
        <param name="start_stops_FAR" type="data" format="bed" label="start_stops_FAR" help="Please run 'ribotaper part 1' to generate the table."/>
    </inputs>
    <outputs>
        <data name="output1" type="data" format="pdf" from_work_dir="merged_metagene.pdf" label="Metagene analysis results for P-sites definition (figures)"/>
        <data name="output2" type="data" format="tabular" from_work_dir="metagene" label="Metagene analysis results for P-sites definition (table)"/>
    </outputs>
    <tests>
        <test>
            <param name="ribo_bam" value="test_ribo.bam" ftype="bam"/>
            <param name="start_stops_FAR" value="annotation_path/start_stops_FAR.bed"  ftype="bed"/>
            <output name="output2" file="metagene"/>
        </test>
    </tests>
    <help><![CDATA[
Overview
--------

RiboTaper is an analysis pipeline for Ribosome Profiling
(Ribo-seq) experiments,
which exploits the triplet periodicity of
ribosomal footprints to call translated regions.
See
https://ohlerlab.mdc-berlin.de/software/RiboTaper_126/ for details.


The Ribotaper Galaxy tool set consists of three tools:

  - ``ribotaper part 1``: creation of annotation files
  - ``ribotaper part 2``: metagene analysis for P-sites definition
  - ``ribotaper part 3``: ribosome profiling

The order of execution should follow:
``ribotaper part 1, part 2 and part 3``.

The current tool is ``ribotaper part 2``,
metagene analysis for P-sites definition.

Output
--------

``Ribotaper part 2`` generates two files:

  - **Metagene analysis results for P-sites definition** in pdf format
  - **Metagene analysis results for P-sites definition** in tablular format

The outputs include the aggregate profiles around the start and stop codons for the 5'-end of different Ribo-seq read lengths.
Deciding which Ribo-seq read length to use at which distance cutoff to define P-sites position is the critical decision for the whole RiboTaper pipeline.
These plots should help you decide which read lengths to use and with which cutoff.
Ideally, the user should pick up the read lengths which show a specific frame preference (same color preference for all the 4 subplots) and a peak around a specific distance on the start codon.
Sometimes a peak at the stop codon is also visible, but often in a different frame. This may have biological relevance, but it is still not very well explained by the community.
As seen in the example, taken from the Ribo-seq data of our publication, the 29 nt reads show a very nice frame preference and a peak of 12 nt distance from the annotated start codons. Which means the 29 nt reads with a 12 distance cutoff can be chosen.
Usually reads around 29 nt with 12 nt distance cutoff are the outcome of many Ribo-seq experiments, however, despite biochemical constraint about the size of ribosome-protected fragments, the outcome of such analysis is heavily influenced by the experimental protocol used.
More read lengths can be chosen, but they have to display a strong frame preference.

From the output, user shall determine the appropriate
read lengths and cutoffs which are required
for running ``ribotaper part 3``, ribosome profiling.

]]></help>
    <citations>
        <citation type="doi">10.1038/nmeth.3688</citation>
    </citations>
</tool>