annotate lastz_d.xml @ 5:bd84ff27bc16 draft

planemo upload for repository https://github.com/galaxyproject/tools-iuc/tree/master/tools/lastz commit a0a0480a8df511d23ed6101a489ca06337f5ed56

<tool id="lastz_d_wrapper" name="LASTZ_D" version="1.3">
    <description>: estimate substitution scores matrix</description>
    <macros>
    	<import>lastz_macros.xml</import>
    </macros>
    <requirements>
        <requirement type="package" version="@LASTZ_CONDA_VERSION@">lastz</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        lastz_D
        @TARGET_INPUT_COMMAND_LINE@
        '${query}'
        #if $score_file:
            '--inferonly=${score_file}'
        #else:
            --inferonly
        #end if
        '--infscores=${output}'
        ]]>
    </command>
    <inputs>
        <expand macro="target_input"/>
        <param name="query" format="fasta,fasta.gz,fastq.gz" type="data" label="Select QUERY sequence(s)" help="These are the sequences that you are aligning against TARGET"/>
        <param name="score_file" type="data" format="txt" optional="true" label="Control file for inference" argument="--inferonly[=control_file]" help="Optional controf file. If nothing is selected, LASTZ_D uses default described in the manual"/>
     </inputs>
    <outputs>
        <data format="txt" name="output" label="${tool.name} on ${on_string}: substituion matrix"/>
    </outputs>
    <tests>
        <test>
            <param name="ref_source" value="history" />
            <param name="target" value="chrM_human.fa" />
            <param name="query" value="chrM_mouse.fa" />
            <output name="output" value="lastz_d_test1.out" />
        </test>
        <test>
            <param name="ref_source" value="history" />
            <param name="target" value="chrM_human.fa" />
            <param name="query" value="chrM_mouse.fa" />
            <param name="score_file" value="lastz_d_ctrl_file.txt" />
            <output name="output" value="lastz_d_test2.out" />
        </test>
    </tests>

    <help><![CDATA[

        **What is does**

        LASTZ_D is a non-integer (**D** stands for Double) version of LASTZ that can be used to estimate substitution matrix that will be used to score alignments. It was developed by `Bob Harris <http://www.bx.psu.edu/~rsharris/>`_ in the lab of Webb Miller at Penn State as a part of LASTZ. Matrix computed by this tool is to be used by LASTZ (see below).

        .. class:: warningmark

        **Read documentation** before proceeding. LASTZ is a complex tool with many parameter options. Fortunately, there is a `great manual <https://lastz.github.io/lastz/>`_ maintained by its author. The two sections that are particularly relevant to the inference of substitution matrix are `Inferring Score Sets <http://www.bx.psu.edu/~rsharris/lastz/README.lastz-1.04.00.html#adv_inference>`_ and `Inference Control File <http://www.bx.psu.edu/~rsharris/lastz/README.lastz-1.04.00.html#fmt_inference>`_.

        **Notes on the inference**

        Inference is achieved by computing the probability of each of the 18 different alignment events (gap open, gap extend, and 16 substitutions). These probabilities are estimated from alignments of the sequences. Of course, at first we don't have alignments, so the process begins by using a generic scoring set to create alignments, infer scores from those, then realign, and so on, until the scores stabilize or "converge". Ungapped alignments are performed until the substitution scores converge, then gapped alignments are performed (holding the substitution scores constant) until the gap penalties converge. In the end you get a matrix like this::

            # (a LASTZ scoring set, created by "LASTZ --infer")

            bad_score          = X:-1781 # used for sub[X][*] and sub[*][X]
            fill_score         = -178    # used when sub[*][*] not otherwise defined
            gap_open_penalty   = 400
            gap_extend_penalty = 30

                  A     C     G     T
            A    72   -79   -49   -97
            C   -79   100  -178   -49
            G   -49  -178   100   -79
            T   -97   -49   -79    72

        This dataset can then be used as an input to the **Read the substitution scores** parameter of LASTZ (Parameter section *Scoring*).

        The iterative process can fail if there's not a lot of sequence to align.  E.g. if after the 4th iteration there's nothing in the central 50% denominators go to zero and the process fails.

        If the sequences you are aligning have GC content different than the usual ACGT 30-20-20-30 split, scoring inference should discover this and give you better alignments.


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