annotate cmsearch.xml @ 8:c9e29ac5d099 draft default tip

"planemo upload for repository https://github.com/bgruening/galaxytools/tree/master/tools/infernal commit a812ed8de433ac4e8b42afd636e70cfbb180d2b9"

<tool id="infernal_cmsearch" name="cmsearch" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@">
    <description>Search covariance model(s) against a sequence database </description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <!--parallelism method="multi" split_inputs="seqdb" split_mode="to_size" split_size="500" merge_outputs="outfile,multiple_alignment_output"></parallelism-->
    <expand macro="requirements"/>
    <expand macro="stdio" />
    <expand macro="xrefs"/>
    <command>
<![CDATA[
        ## a temp file is needed, because the standard tabular output from infernal is not usefull in Galaxy
        ## it will be converted to a tab delimited file and piped to Galaxy
        temp_tabular_output=\$(mktemp) &&

        cmsearch
            ## Infernal Options
            --cpu "\${GALAXY_SLOTS:-2}"
            -o /dev/null
            --tformat $seqdb.ext ##target format: fasta, embl, genbank, ddbj, stockholm, pfam, a2m, afa, clustal, and phylip
            $bottomonly
            $toponly
            $cyk
            $acyk
            $notrunc
            $anytrunc
            $nonull3
            #if str($smxsize) != "128.0"
                --smxsize $smxsize
            #end if
            #if str($mxsize) != "128.0"
                --mxsize $mxsize
            #end if
            --tblout \$temp_tabular_output
            $g
            #if $Z
                -Z $Z
            #end if
            #if $A:
                $A '$multiple_alignment_output'
            #end if
            #if str($inclusion_thresholds_opts.inclusion_thresholds_selector) == "--incE":
                --incE $inclusion_thresholds_opts.incE
            #elif str($inclusion_thresholds_opts.inclusion_thresholds_selector) == "--incT":
                --incT $inclusion_thresholds_opts.incT
            #end if
            #if str($reporting_thresholds_opts.reporting_thresholds_selector) == "-E":
                -E $reporting_thresholds_opts.E
            #elif str($reporting_thresholds_opts.reporting_thresholds_selector) == "-T":
                -T $reporting_thresholds_opts.T
            #end if
            $model_thresholds.cut_ga
            $model_thresholds.cut_nc
            $model_thresholds.cut_tc
            #if $acceleration_huristics.acceleration_huristics_selector == "FZ"
                --FZ $$acceleration_huristics.FZ
            #else
                $acceleration_huristics.acceleration_huristics_selector
                #if $acceleration_huristics.acceleration_huristics_selector == "--mid"
                    --Fmid $acceleration_huristics.Fmid
                #end if
            #end if
            ## CM file from the history or stored as database on disc
            #if str($cm_opts.cm_opts_selector) == "db":
                $cm_opts.database.fields.path
            #else:
                $cm_opts.cmfile
            #end if
            ## sequence file
            '$seqdb'
            2>&1
            &&
            ## 1. replace all lines starting # (comment lines)
            ## 2. replace the first 18 spaces with tabs, 18th field is a free text field (can contain spaces)
            sed -e 's/#.*$//' -e '/^$/d' -e 's/\s\+/\t/g' -e 's/\t/ /18g' \$temp_tabular_output > '$outfile'

]]>
    </command>
    <inputs>

        <param name="seqdb" type="data" format="fasta" label="Sequence database"/>

        <conditional name="cm_opts">
            <param name="cm_opts_selector" type="select" label="Subject covariance models">
              <option value="db" selected="True">Locally installed covariance models</option>
              <option value="histdb">Covariance model from your history</option>
            </param>
            <when value="db">
                <param name="database" type="select" label="Covariance models">
                    <options from_file="infernal.loc">
                      <column name="value" index="0"/>
                      <column name="name" index="1"/>
                      <column name="path" index="2"/>
                    </options>
                </param>
            </when>
            <when value="histdb">
                <param name="cmfile" type="data" format="cm" label="Covariance models file from the history."/>
            </when>
        </conditional>

        <param argument="-g" truevalue="-g" falsevalue="" checked="False" type="boolean"
            label="Turn on the glocal alignment algorithm" help="... global with respect to the query model and local with respect to the target database."/>
        <param argument="-Z" type="float" min="0" optional="true" label="Calculate E-values as if the search space size is 'x' megabases (Mb)" help=""/>

        <param argument="--bottomonly" truevalue="--bottomonly" falsevalue="" checked="False" type="boolean"
            label="Only search the bottom (Crick) strand of target sequences" help="in the sequence database"/>
        <param argument="--toponly" truevalue="--toponly" falsevalue="" checked="False" type="boolean"
            label="Only search the top (Watson) strand of target sequences" help="in the sequence database"/>

        <param argument="--cyk" truevalue="--cyk" falsevalue="" checked="False" type="boolean"
            label="Use the CYK algorithm, not Inside, to determine the final score of all hits" help=""/>
        <param argument="--acyk" truevalue="--cyk" falsevalue="" checked="False" type="boolean"
            label="Use the CYK algorithm to align hits" help="By default, the Durbin/Holmes optimal accuracy algorithm is used, which finds the alignment that maximizes the expected accuracy of all aligned residues."/>

        <param argument="--notrunc" truevalue="--notrunc" falsevalue="" checked="False" type="boolean"
            label="Skip truncated hit detection" help=""/>
        <param argument="--anytrunc" truevalue="--anytrunc" falsevalue="" checked="false" type="boolean"
            label="Allow full and truncated hits anywhere within sequences" help=""/>
        <param argument="--nonull3" truevalue="--nonull3" falsevalue="" checked="false" type="boolean"
            label="Turn off the null3 CM score corrections for biased composition" help="This correction is not used during the HMM filter stages."/>
        <param argument="--mxsize" type="float" value="128.0" min="0.1"
            label="Set the maximum allowable CM DP matrix size to 'x' megabytes" help=""/>
        <param argument="--smxsize" type="float" value="128.0" min="0.1"
            label="Set the maximum allowable CM search DP matrix size to 'x' megabytes." help=""/>

        <!-- accelleration pipeline -->
        <conditional name="acceleration_huristics">
            <param name="acceleration_huristics_selector" type="select" label="Options controlling acceleration heuristics" help="These options are, in order from least strict (slowest but most sensitive) to most strict (fastest but least sensitive)">
                <option value="--max">Turn all heuristic filters off (--max)</option>
                <option value="--nohmm">Skip all HMM filter stages, use only CM (--nohmm)</option>
                <option value="--mid">Skip first two HMM filter stages (SSV and Vit) (--mid)</option>
                <option value="--default" selected="true">Run search space size-dependent pipeline (--default)</option>
                <option value="--rfam">Use a strict filtering strategy devised for large databases (more than 20 Gb) (--rfam)</option>
                <option value="--hmmonly">Use HMM only, don't use a CM at all (--hmmonly)</option>
                <option value="FZ">set filters to defaults used for a search space of size 'x' Mb (--FZ)</option>
            </param>
            <when value="--max">
            </when>
            <when value="--nohmm">
            </when>
            <when value="--mid">
                    <param argument="--Fmid" type="float" value="0.02" label="P-value threshold for HMM stages"/>
            </when>
            <when value="--default">
            </when>
            <when value="--rfam">
            </when>
            <when value="--hmmonly">
            </when>
            <when value="FZ">
                <param argument="--FZ" type="float" value="" label="Size of search space in Mb"/>
            </when>
        </conditional>



        <!-- Options for model-specific score thresholding -->

        <section name="model_thresholds" title="Options controlling model-specific reporting thresholds" help="Curated CM databases may define specific bit score thresholds for each CM, superseding any thresholding based on statistical significance alone.">
            <param argument="--cut_ga" truevalue="--cut_ga" falsevalue="" checked="false" type="boolean"
                label="Use CM's GA gathering cutoffs as reporting thresholds" help="GA thresholds are generally considered to be the reliable curated thresholds defining family membership"/>
            <param argument="--cut_nc" truevalue="--cut_nc" falsevalue="" checked="false" type="boolean"
                label="use CM's NC noise cutoffs as reporting thresholds" help="NC thresholds are generally considered to be the score of the highest-scoring known false positive."/>
            <param argument="--cut_tc" truevalue="--cut_tc" falsevalue="" checked="false" type="boolean"
                label="use CM's TC trusted cutoffs as reporting thresholds" help="TC thresholds are generally considered to be the score of the lowest-scoring known true positive that is above all known false positives."/>
        </section>

        <!-- Options for inclusion thresholds -->
        <conditional name="inclusion_thresholds_opts">
            <param name="inclusion_thresholds_selector" type="select" label="Inclusion thresholds"
            help="Inclusion thresholds are stricter than reporting thresholds. Inclusion thresholds control which hits are considered to be reliable enough to be included in an output alignment or in a possible subsequent search round, or marked as significant (”!”) as opposed to questionable (”?”) in hit output.">
                <option value="" selected="true">default</option>
                <option value="--incE">Use E-value</option>
                <option value="--incT">Use bit score</option>
            </param>
            <when value=""/>
            <when value="--incE">
                <param name="incE" type="float" value="0.01" label="Use E-value" help="of &lt;= X as the hit inclusion threshold.">
                    <sanitizer>
                        <valid initial="string.printable">
                            <remove value="&apos;"/>
                        </valid>
                    </sanitizer>
                </param>
            </when>
            <when value="--incT">
                <param name="incT" type="integer" value="0" label="Use bit score" help="of >= X as the hit inclusion threshold.">
                    <sanitizer>
                        <valid initial="string.printable">
                            <remove value="&apos;"/>
                        </valid>
                    </sanitizer>
                </param>
            </when>
        </conditional>

        <!-- Options controlling reporting thresholds -->

        <conditional name="reporting_thresholds_opts">
            <param name="reporting_thresholds_selector" type="select" label="reporting thresholds"
            help="Reporting thresholds control which hits are reported in output files">
                <option value="" selected="true">default</option>
                <option value="-E">Use E-value</option>
                <option value="-T">Use bit score</option>
            </param>
            <when value=""/>
            <when value="-E">
                <param name="E" type="float" value="10.0" label="Use E-value" help="of &lt;= X as the hit reporting threshold. The default is 10.0, meaning that on average, about 10 false positives will be reported per query, so you can see the top of the noise and decide for yourself if it’s really noise.">
                    <sanitizer>
                        <valid initial="string.printable">
                            <remove value="&apos;"/>
                        </valid>
                    </sanitizer>
                </param>
            </when>
            <when value="-T">
                <param name="T" type="integer" value="0" label="Use bit score" help="of >= X as the hit reporting threshold.">
                    <sanitizer>
                        <valid initial="string.printable">
                            <remove value="&apos;"/>
                        </valid>
                    </sanitizer>
                </param>
            </when>
        </conditional>

        <param argument="-A" truevalue="-A" falsevalue="" checked="False" type="boolean"
            label="Save a multiple alignment of all significant hits" help="... those satisfying inclusion thresholds"/>
        <param argument="--noali" type="boolean" truevalue="--noali" falsevalue="" checked="false"
            label="Omit the alignment section from the main input" help="This can greatly reduce the output volume"/>
        <param argument="--verbose" type="boolean" truevalue="--verbose" falsevalue="" checked="false"
            label="Include extra search pipeline statistics in the main output" help="They include filter survival statistics for truncated hit detection and number of envelopes discarded due to matrix size overflows."/>
    </inputs>
    <outputs>

        <data format="tabular" name="outfile" label="cmsearch on ${on_string}"/>
        <data format="tabular" name="multiple_alignment_output" label="cmsearch on ${on_string} (multi alignment)">
            <filter>A is True</filter>
        </data>

    </outputs>
    <tests>
        <test>
            <conditional name="cm_opts">
                <param name="cm_opts_selector" value="histdb"/>
                <param name="cmfile" value="cmsearch_input1.cm"/>
            </conditional>
            <param name="seqdb" value="cmsearch_input2.fa"/>
            <output name="outfile" file="cmsearch_result.tabular"/>
        </test>
    </tests>

    <help>
<![CDATA[


**What it does**

cmsearch belongs to the INFERNAL software package that allows you to make consensus RNA secondary structure profiles, and use them to search nucleic acid sequence databases for homologous RNAs, or to create new structure-based multiple sequence alignments.
You can use your model to search for new homologues of your RNA family. cmsearch is used to search one or more covariance models (CMs) against a sequence database. cmsearch searches both strands of each sequence in the target database, and returns alignments for high scoring hits.

To build CMs from multiple alignments, see cmbuild (build covariance models).


**Input**

The CM query file must have been calibrated for E-values with cmcalibrate. As a special exception, any models CM query files that have zero basepairs need not be calibrated.


**Options**

- *Turn on the glocal alignment algorithm*: global with respect to the query model and local with respect to the target database. By default, the local alignment algorithm is used which is local with respect to both the target sequence and the model. In local mode, the alignment to span two or more subsequences if necessary (e.g. if the structures of the query model and target sequence are only partially shared), allowing certain large insertions and deletions in the structure to be penalized differently than normal indels. Local mode performs better on empirical benchmarks and is significantly more sensitive for remote homology detection. Empirically, glocal searches return many fewer hits than local searches, so glocal may be desired for some applications. With *Turn on the glocal alignment algorithm*, all models must be calibrated, even those with zero basepairs.

- *Only search the bottom (Crick) strand of target sequences*: Hits can occur on either the top (Watson) or bottom (Crick) strand of the target sequence. By default, both strands are searched.

- *Only search the top (Watson) strand of target sequences*: Hits can occur on either the top (Watson) or bottom (Crick) strand of the target sequence. By default, both strands are searched.

- *Use the CYK algorithm, not Inside, to determine the final score of all hits*: If selecting "yes", the CYK algorithm instead of the CM Inside algorithm (the SCFG analog of the HMM Forward algorithm) is used.

- *Use the CYK algorithm to align hits*: By default, the Durbin/Holmes optimal accuracy algorithm is used, which finds the alignment that maximizes the expected accuracy of all aligned residues.

- *Turn off truncated hit detection*: Turns off truncated hit detection and will reduce the running time most significantly for target files that include many short sequences.

- *Turn off all filters, and run non-banded Inside on every full-length target sequence*: This increases sensitivity somewhat, at an extremely large cost in speed.

- *Turn off all HMM filter stages*: The CYK filter, using QDBs, will be run on every full-length target sequence and will enforce a P-value threshold of 0.0001. Each subsequence that survives CYK will be passed to Inside, which will also use QDBs (but a looser set). This increases sensitivity somewhat, at a very large cost in speed.

- *Turn off the HMM SSV and Viterbi filter stages*:Sets remaining HMM filter thresholds to 0.02 by default. This may increase sensitivity, at a significant cost in speed.

- *Inclusion thresholds*: *Use E-value* - Use an E-value as the hit inclusion threshold. The default is 0.01, meaning that on average, about 1 false positive would be expected in every 100 searches with different query sequences. *Use Bit Score* - Instead of using E-values for setting the inclusion threshold, instead use a bit score as the hit inclusion threshold. By default this option is unset.


**Output Options**

- *reporting thresholds*: Hits are ranked by statistical significance (E-value). By *default*, all hits with an E-value <= 10 are reported. The following options allow you to change the default *E-value* reporting thresholds, or to use *bit score* thresholds instead.


Output columns:

(1)  rank

(2)  E-value

(3)  score

(4)  bias

(5)  sequence

(6)  start

(7)  end

(8)  mdl

(9)  trunc

(10)  gc

(11)  description

----   --------- ------ -----  ----------- ------- -------   --- ----- ----  -----------

!   1.3e-18   71.5   0.0  NC_013790.1  362026  361955 -  cm    no 0.50  Methanobrevibacter ruminantium M1

!   3.3e-18   70.2   0.0  NC_013790.1 2585265 2585193 -  cm    no 0.60  Methanobrevibacter ruminantium M1


For further questions please refere to the Infernal `Userguide <http://eddylab.org/infernal/Userguide.pdf>`_.

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


</tool>