annotate lastz_d.xml @ 11:37b497aa133f draft default tip

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

<tool id="lastz_d_wrapper" name="LASTZ_D" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@">
    <description>: estimate substitution scores matrix</description>
    <macros>
    	<import>lastz_macros.xml</import>
    </macros>
    <expand macro="bio_tools"/>
    <requirements>
        <requirement type="package" version="@TOOL_VERSION@">lastz</requirement>
        <requirement type="package" version="1.0.8">bzip2</requirement>
    </requirements>
    <command detect_errors="exit_code"><![CDATA[
        lastz_D
        @TARGET_INPUT_COMMAND_LINE@
        @query_input@
        #if $score_file:
            '--inferonly=${score_file}'
        #else:
            --inferonly
        #end if
        '--infscores=${output}'
        ]]>
    </command>
    <inputs>
        <expand macro="target_input"/>
        <param name="query" format="fasta,fastq,fasta.gz,fastq.gz,fastq.bz2" 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}: substitution 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 <https://www.bx.psu.edu/~rsharris/lastz/README.lastz-1.04.03.html#adv_inference>`_ and
`Inference Control File <https://www.bx.psu.edu/~rsharris/lastz/README.lastz-1.04.03.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>