annotate tools/ncbi_blast_plus/ncbi_macros.xml @ 21:7538e2bfcd41 draft

v0.2.00, for NCBI BLAST+ 2.5.0 via bioconda or tool_dependencies.xml

<macros>
    <token name="@WRAPPER_VERSION@">0.2.00</token>
    <xml name="parallelism">
        <!-- If job splitting is enabled, break up the query file into parts -->
        <parallelism method="multi" split_inputs="query" split_mode="to_size" split_size="1000" merge_outputs="output1" />
    </xml>
    <xml name="preamble">
        <requirements>
            <requirement type="package" version="2.5.0">blast</requirement>
        </requirements>
        <stdio>
            <!-- Anything other than zero is an error -->
            <exit_code range="1:" />
            <!-- Might see negative return codes for Unix signals via Python subprocess -->
            <exit_code range=":-1" />
            <!-- In case the return code has not been set properly check stderr too -->
            <regex match="Error:" />
            <regex match="Exception:" />
        </stdio>
        <version_command>@BINARY@ -version</version_command>
    </xml>
    <xml name="output_change_format">
        <change_format>
            <when input="output.out_format" value="0" format="txt"/>
            <when input="output.out_format" value="0 -html" format="html"/>
            <when input="output.out_format" value="2" format="txt"/>
            <when input="output.out_format" value="2 -html" format="html"/>
            <when input="output.out_format" value="4" format="txt"/>
            <when input="output.out_format" value="4 -html" format="html"/>
            <when input="output.out_format" value="5" format="blastxml"/>
        </change_format>
    </xml>
    <xml name="input_out_format">
        <conditional name="output">
            <param name="out_format" type="select" label="Output format">
                <option value="6">Tabular (standard 12 columns)</option>
                <option value="ext" selected="True">Tabular (extended 25 columns)</option>
                <option value="cols">Tabular (select which columns)</option>
                <option value="5">BLAST XML</option>
                <option value="0">Pairwise text</option>
                <option value="0 -html">Pairwise HTML</option>
                <option value="2">Query-anchored text</option>
                <option value="2 -html">Query-anchored HTML</option>
                <option value="4">Flat query-anchored text</option>
                <option value="4 -html">Flat query-anchored HTML</option>
                <!--
                <option value="-outfmt 11">BLAST archive format (ASN.1)</option>
                -->
            </param>
            <when value="6"/>
            <when value="ext"/>
            <when value="cols">
                <param name="std_cols" type="select" multiple="true" display="checkboxes" label="Standard columns">
                    <option selected="true" value="qseqid">qseqid = Query Seq-id (ID of your sequence)</option>
                    <option selected="true" value="sseqid">sseqid = Subject Seq-id (ID of the database hit)</option>
                    <option selected="true" value="pident">pident = Percentage of identical matches</option>
                    <option selected="true" value="length">length = Alignment length</option>
                    <option selected="true" value="mismatch">mismatch = Number of mismatches</option>
                    <option selected="true" value="gapopen">gapopen = Number of gap openings</option>
                    <option selected="true" value="qstart">qstart = Start of alignment in query</option>
                    <option selected="true" value="qend">qend = End of alignment in query</option>
                    <option selected="true" value="sstart">sstart = Start of alignment in subject (database hit)</option>
                    <option selected="true" value="send">send = End of alignment in subject (database hit)</option>
                    <option selected="true" value="evalue">evalue = Expectation value (E-value)</option>
                    <option selected="true" value="bitscore">bitscore = Bit score</option>
                </param>
                <param name="ext_cols" type="select" multiple="true" display="checkboxes" label="Extended columns">
                    <option value="sallseqid">sallseqid = All subject Seq-id(s), separated by a ';'</option>
                    <option value="score">score = Raw score</option>
                    <option value="nident">nident = Number of identical matches</option>
                    <option value="positive">positive = Number of positive-scoring matches</option>
                    <option value="gaps">gaps = Total number of gaps</option>
                    <option value="ppos">ppos = Percentage of positive-scoring matches</option>
                    <option value="qframe">qframe = Query frame</option>
                    <option value="sframe">sframe = Subject frame</option>
                    <option value="qseq">qseq = Aligned part of query sequence</option>
                    <option value="sseq">sseq = Aligned part of subject sequence</option>
                    <option value="qlen">qlen = Query sequence length</option>
                    <option value="slen">slen = Subject sequence length</option>
                    <option value="salltitles">salltitles = All subject title(s), separated by a '&lt;&gt;'</option>
                </param>
                <param name="ids_cols" type="select" multiple="true" display="checkboxes" label="Other identifier columns">
                    <option value="qgi">qgi = Query GI</option>
                    <option value="qacc">qacc = Query accesion</option>
                    <option value="qaccver">qaccver = Query accesion.version</option>
                    <option value="sallseqid">sallseqid = All subject Seq-id(s), separated by a ';'</option>
                    <option value="sgi">sgi = Subject GI</option>
                    <option value="sallgi">sallgi = All subject GIs</option>
                    <option value="sacc">sacc = Subject accession</option>
                    <option value="saccver">saccver = Subject accession.version</option>
                    <option value="sallacc">sallacc = All subject accessions</option>
                    <option value="stitle">stitle = Subject Title</option>
                </param>
                <param name="misc_cols" type="select" multiple="true" display="checkboxes" label="Miscellaneous columns">
                    <option value="sstrand">sstrand = Subject Strand</option>
                    <!-- Is it really worth including 'frames' given have 'qframe' and 'sframe'? -->
                    <option value="frames">frames = Query and subject frames separated by a '/'</option>
                    <option value="btop">btop = Blast traceback operations (BTOP)</option>
                    <option value="qcovs">qcovs = Query Coverage Per Subject</option>
                    <option value="qcovhsp">qcovhsp = Query Coverage Per HSP</option>
                </param>
                <param name="tax_cols" type="select" multiple="true" display="checkboxes" label="Taxonomy columns">
                    <option value="staxids">staxids = unique Subject Taxonomy ID(s), separated by a ';' (in numerical order)</option>
                    <!-- TODO, how to handle the taxonomy data file dependency? If missing these give N/A -->
                    <option value="sscinames">sscinames = unique Subject Scientific Name(s), separated by a ';'</option>
                    <option value="scomnames">scomnames = unique Subject Common Name(s), separated by a ';'</option>
                    <option value="sblastnames">sblastnames = unique Subject Blast Name(s), separated by a ';' (in alphabetical order)</option>
                    <option value="sskingdoms">sskingdoms = unique Subject Super Kingdom(s), separated by a ';' (in alphabetical order)</option>
                </param>
            </when>
            <when value="5"/>
            <when value="0"/>
            <when value="0 -html"/>
            <when value="2"/>
            <when value="2 -html"/>
            <when value="4"/>
            <when value="4 -html"/>
        </conditional>
    </xml>
    <xml name="input_scoring_matrix">
        <param name="matrix" type="select" label="Scoring matrix">
            <option value="BLOSUM90">BLOSUM90</option>
            <option value="BLOSUM80">BLOSUM80</option>
            <option value="BLOSUM62" selected="true">BLOSUM62 (default)</option>
            <option value="BLOSUM50">BLOSUM50</option> 
            <option value="BLOSUM45">BLOSUM45</option>
            <option value="PAM250">PAM250</option>
            <option value="PAM70">PAM70</option>
            <option value="PAM30">PAM30</option>
        </param>
    </xml>
    <xml name="input_query_gencode">
        <param name="query_gencode" type="select" label="Query genetic code">
            <!-- See http://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi for details -->
            <option value="1" selected="True">1. Standard</option>
            <option value="2">2. Vertebrate Mitochondrial</option>
            <option value="3">3. Yeast Mitochondrial</option>
            <option value="4">4. Mold, Protozoan, and Coelenterate Mitochondrial Code and the Mycoplasma/Spiroplasma Code</option>
            <option value="5">5. Invertebrate Mitochondrial</option>
            <option value="6">6. Ciliate, Dasycladacean and Hexamita Nuclear Code</option>
            <option value="9">9. Echinoderm Mitochondrial</option>
            <option value="10">10. Euplotid Nuclear</option>
            <option value="11">11. Bacteria and Archaea</option>
            <option value="12">12. Alternative Yeast Nuclear</option>
            <option value="13">13. Ascidian Mitochondrial</option>
            <option value="14">14. Flatworm Mitochondrial</option>
            <option value="15">15. Blepharisma Macronuclear</option>
            <option value="16">16. Chlorophycean Mitochondrial Code</option>
            <option value="21">21. Trematode Mitochondrial Code</option>
            <option value="22">22. Scenedesmus obliquus mitochondrial Code</option>
            <option value="23">23. Thraustochytrium Mitochondrial Code</option>
            <option value="24">24. Pterobranchia mitochondrial code</option>
        </param>
    </xml>
    <xml name="input_db_gencode">
        <param name="db_gencode" type="select" label="Database/subject genetic code">
            <!-- See http://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi for details -->
            <option value="1" selected="True">1. Standard</option>
            <option value="2">2. Vertebrate Mitochondrial</option>
            <option value="3">3. Yeast Mitochondrial</option>
            <option value="4">4. Mold, Protozoan, and Coelenterate Mitochondrial Code and the Mycoplasma/Spiroplasma Code</option>
            <option value="5">5. Invertebrate Mitochondrial</option>
            <option value="6">6. Ciliate, Dasycladacean and Hexamita Nuclear Code</option>
            <option value="9">9. Echinoderm Mitochondrial</option>
            <option value="10">10. Euplotid Nuclear</option>
            <option value="11">11. Bacteria and Archaea</option>
            <option value="12">12. Alternative Yeast Nuclear</option>
            <option value="13">13. Ascidian Mitochondrial</option>
            <option value="14">14. Flatworm Mitochondrial</option>
            <option value="15">15. Blepharisma Macronuclear</option>
            <option value="16">16. Chlorophycean Mitochondrial Code</option>
            <option value="21">21. Trematode Mitochondrial Code</option>
            <option value="22">22. Scenedesmus obliquus mitochondrial Code</option>
            <option value="23">23. Thraustochytrium Mitochondrial Code</option>
            <option value="24">24. Pterobranchia mitochondrial code</option>
        </param>
    </xml>
    <xml name="input_conditional_nucleotide_db">
        <conditional name="db_opts">
            <param name="db_opts_selector" type="select" label="Subject database/sequences">
              <option value="db" selected="True">Locally installed BLAST database</option>
              <option value="histdb">BLAST database from your history</option>
              <option value="file">FASTA file from your history (see warning note below)</option>
            </param>
            <when value="db">
                <param name="database" type="select" multiple="true" label="Nucleotide BLAST database">
                    <options from_data_table="blastdb" />
                </param>
                <param name="histdb" type="hidden" value="" />
                <param name="subject" type="hidden" value="" /> 
            </when>
            <when value="histdb">
                <param name="database" type="hidden" value="" />
                <param name="histdb" type="data" format="blastdbn" label="Nucleotide BLAST database" />
                <param name="subject" type="hidden" value="" />
            </when>
            <when value="file">
                <param name="database" type="hidden" value="" />
                <param name="histdb" type="hidden" value="" />
                <param name="subject" type="data" format="fasta" label="Nucleotide FASTA file to use as database"/> 
            </when>
        </conditional>
    </xml>
    <xml name="input_conditional_protein_db">
        <conditional name="db_opts">
            <param name="db_opts_selector" type="select" label="Subject database/sequences">
              <option value="db" selected="True">Locally installed BLAST database</option>
              <option value="histdb">BLAST database from your history</option>
              <option value="file">FASTA file from your history (see warning note below)</option>
            </param>
            <when value="db">
                <param name="database" type="select" multiple="true" label="Protein BLAST database">
                    <options from_data_table="blastdb_p" />
                </param>
                <param name="histdb" type="hidden" value="" />
                <param name="subject" type="hidden" value="" />
            </when>
            <when value="histdb">
                <param name="database" type="hidden" value="" />
                <param name="histdb" type="data" format="blastdbp" label="Protein BLAST database" />
                <param name="subject" type="hidden" value="" />
            </when>
            <when value="file">
                <param name="database" type="hidden" value="" />
                <param name="histdb" type="hidden" value="" />
                <param name="subject" type="data" format="fasta" label="Protein FASTA file to use as database"/> 
            </when>
        </conditional>
    </xml>
    <xml name="input_conditional_pssm">
        <conditional name="db_opts">
            <param name="db_opts_selector" type="select" label="Protein domain database (PSSM)">
              <option value="db" selected="True">Locally installed BLAST protein domain database</option>
              <option value="histdb">BLAST protein domain database from your history</option>
            </param>
            <when value="db">
                <param name="database" type="select" label="Protein domain database">
                    <options from_data_table="blastdb_d" />
                </param>
                <param name="histdb" type="hidden" value="" />
                <param name="subject" type="hidden" value="" />
            </when>
            <when value="histdb">
                <param name="database" type="hidden" value="" />
                <param name="histdb" type="data" format="blastdbd" label="Protein domain database" />
                <param name="subject" type="hidden" value="" />
            </when>
        </conditional>
    </xml>
    <xml name="input_conditional_choose_db_type">
        <conditional name="db_opts">
            <param name="db_type" type="select" label="Type of BLAST database">
              <option value="nucl" selected="True">Nucleotide</option>
              <option value="prot">Protein</option>
            </param>
            <when value="nucl">
                <param name="database" type="select" multiple="true" label="Nucleotide BLAST database">
                    <options from_data_table="blastdb" />
                </param>
            </when>
            <when value="prot">
                <param name="database" type="select" multiple="true" label="Protein BLAST database">
                    <options from_data_table="blastdb_p" />
                </param>
            </when>
        </conditional>
    </xml>
    <xml name="input_parse_deflines">
        <param name="parse_deflines" type="boolean" label="Should the query and subject defline(s) be parsed?" truevalue="-parse_deflines" falsevalue="" checked="false" help="This affects the formatting of the query/subject ID strings"/>
    </xml>
    <xml name="input_filter_query_default_false">
        <param name="filter_query" type="boolean" label="Filter out low complexity regions (with SEG)" truevalue="-seg yes" falsevalue="-seg no" checked="false" />
    </xml>
    <xml name="input_filter_query_default_true">
        <param name="filter_query" type="boolean" label="Filter out low complexity regions (with SEG)" truevalue="-seg yes" falsevalue="-seg no" checked="true" />
    </xml>
    <xml name="input_max_hits">
        <param name="max_hits" type="integer" value="0" label="Maximum hits to show" help="Use zero for default limits">
            <validator type="in_range" min="0" />
        </param>        
    </xml>
    <xml name="input_evalue">
        <param name="evalue_cutoff" type="float" size="15" value="0.001" label="Set expectation value cutoff" />
    </xml>
    <xml name="input_word_size">
        <param name="word_size" type="integer" value="0" label="Word size for wordfinder algorithm" help="Use zero for default, otherwise minimum 2.">
            <validator type="in_range" min="0" />
        </param>        
    </xml>
    <xml name="input_strand">
        <param name="strand" type="select" label="Query strand(s) to search against database/subject">
            <option value="-strand both">Both</option>
            <option value="-strand plus">Plus (forward)</option>
            <option value="-strand minus">Minus (reverse complement)</option>
        </param>
    </xml>
    <xml name="input_qcov_hsp_perc">
        <param name="qcov_hsp_perc" type="float" value="0" min="0" max="100" label="Minimum query coverage per hsp (percentage, 0 to 100)" help="See also the output column qcovhsp"/>
    </xml>
    <xml name="advanced_options">
        <conditional name="adv_opts">
            <param name="adv_opts_selector" type="select" label="Advanced Options">
              <option value="basic" selected="True">Hide Advanced Options</option>
              <option value="advanced">Show Advanced Options</option>
            </param>
            <when value="basic" />
            <when value="advanced">
                <yield />
            </when>
        </conditional>
    </xml>
    <xml name="advanced_optional_id_files">
        <conditional name="adv_optional_id_files_opts">
            <param name="adv_optional_id_files_opts_selector" type="select"
                   label="Restrict search of database to a given set of ID's"
		   help="This feature provides a means to exclude ID's from a BLAST database search. The expectation values in the BLAST results are based upon the sequences actually searched, and not on the underlying database. Note this cannot be used when comparing against a FASTA file.">
                <option value="none" selected="True">No restriction, search the entire database</option>
                <option value="gilist">GI identifiers</option>
                <option value="negative_gilist">Negative GI identifiers</option>
                <option value="seqidlist">Sequence identifiers (SeqId's)</option>
            </param>
            <when value="none" />
            <when value="gilist">
                <param name="gilist" type="data" format="txt" label="Restrict search of database to GI's listed in this file"
                       help="This option is only available for database searches."/>
            </when>
            <when value="negative_gilist">
                <param name="negative_gilist" type="data" format="txt" label="Restrict search of database to everything except the GI's listed in this file"
                       help="This option is only available for database searches."/>
            </when>
            <when value="seqidlist">
                <param name="seqidlist" type="data" format="txt" label=" Restrict search of database to list of SeqId's"
                       help="This option is only available for database searches."/>
            </when>
        </conditional>
    </xml>
    <token name="@ADV_QCOV_HSP_PERC@">
#if float(str($adv_opts.qcov_hsp_perc)) &gt; 0:
    -qcov_hsp_perc $adv_opts.qcov_hsp_perc
#end if
    </token>
    <token name="@ADV_ID_LIST_FILTER@">
#if $adv_opts.adv_optional_id_files_opts.adv_optional_id_files_opts_selector == 'negative_gilist':
    -negative_gilist $adv_opts.adv_optional_id_files_opts.negative_gilist
#elif $adv_opts.adv_optional_id_files_opts.adv_optional_id_files_opts_selector == 'gilist':
    -gilist $adv_opts.adv_optional_id_files_opts.gilist
#elif $adv_opts.adv_optional_id_files_opts.adv_optional_id_files_opts_selector == 'seqidlist':
    -seqidlist $adv_opts.adv_optional_id_files_opts.seqidlist
#end if
    </token>
    <token name="@THREADS@">-num_threads "\${GALAXY_SLOTS:-8}"</token>
    <token name="@BLAST_DB_SUBJECT@">
#if $db_opts.db_opts_selector == "db":
  -db "${' '.join(str( $db_opts.database.fields.path ).split( ',' ))}"
#elif $db_opts.db_opts_selector == "histdb":
  -db "${os.path.join($db_opts.histdb.extra_files_path,'blastdb')}"
#else:
  -subject "$db_opts.subject"
#end if
    </token>
    <token name="@BLAST_OUTPUT@">-out "$output1"
##Set the extended list here so when we add things, saved workflows are not affected
#if str($output.out_format)=="ext":
    -outfmt "6 std sallseqid score nident positive gaps ppos qframe sframe qseq sseq qlen slen salltitles"
#elif str($output.out_format)=="cols"
##Pick your own columns. Galaxy gives us it comma separated, BLAST+ wants space separated:
##TODO - Can we catch the user picking no columns and raise an error here?
#set cols = (str($output.std_cols)+","+str($output.ext_cols)+","+str($output.ids_cols)+","+str($output.misc_cols)+","+str($output.tax_cols)).replace("None", "").replace(",,", ",").replace(",", " ").strip()
    -outfmt "6 $cols"
#else:
    -outfmt $output.out_format
#end if
    </token>
    <token name="@ADV_FILTER_QUERY@">$adv_opts.filter_query</token>
    <token name="@ADV_MAX_HITS@">
## Need int(str(...)) because $adv_opts.max_hits is an InputValueWrapper object not a string
## Note -max_target_seqs used to simply override -num_descriptions and -num_alignments
## but this was changed in BLAST+ 2.2.27 onwards to force their use (raised with NCBI)
#if (str($adv_opts.max_hits) and int(str($adv_opts.max_hits)) > 0):
#if str($output.out_format) in ["6", "ext", "cols", "5"]:
## Most output formats use this, including tabular and XML:
-max_target_seqs $adv_opts.max_hits
#else
## Text and HTML output formats 0-4 currently need this instead:
-num_descriptions $adv_opts.max_hits -num_alignments $adv_opts.max_hits
#end if
#end if
    </token>
    <token name="@ADV_WORD_SIZE@">
#if (str($adv_opts.word_size) and int(str($adv_opts.word_size)) > 0):
-word_size $adv_opts.word_size
#end if
$adv_opts.parse_deflines
    </token>
    <!-- @ON_DB_SUBJECT@ is for use with @BLAST_DB_SUBJECT@ -->
    <token name="@ON_DB_SUBJECT@">#if str($db_opts.db_opts_selector)=='db'
${db_opts.database}
#elif str($db_opts.db_opts_selector)=='histdb'
${db_opts.histdb.name}
#else
${db_opts.subject.name}
#end if</token>
    <token name="@REFERENCES@">
Peter J. A. Cock, John M. Chilton, Björn Grüning, James E. Johnson, Nicola Soranzo (2015).
NCBI BLAST+ integrated into Galaxy. *GigaScience* 4:39
http://dx.doi.org/10.1186/s13742-015-0080-7

Christiam Camacho et al. (2009).
BLAST+: architecture and applications.
*BMC Bioinformatics* 15;10:421.
http://dx.doi.org/10.1186/1471-2105-10-421

This wrapper is available to install into other Galaxy Instances via the Galaxy
Tool Shed at http://toolshed.g2.bx.psu.edu/view/devteam/ncbi_blast_plus
    </token>
    <xml name="blast_citations">
        <citations>
            <citation type="doi">10.1186/1471-2105-10-421</citation>
            <citation type="doi">10.1186/s13742-015-0080-7</citation>
        </citations>
    </xml>
    <token name="@OUTPUT_FORMAT@">**Output format**

Because Galaxy focuses on processing tabular data, the default output of this
tool is tabular. The standard BLAST+ tabular output contains 12 columns:

====== ========= ============================================
Column NCBI name Description
------ --------- --------------------------------------------
     1 qseqid    Query Seq-id (ID of your sequence)
     2 sseqid    Subject Seq-id (ID of the database hit)
     3 pident    Percentage of identical matches
     4 length    Alignment length
     5 mismatch  Number of mismatches
     6 gapopen   Number of gap openings
     7 qstart    Start of alignment in query
     8 qend      End of alignment in query
     9 sstart    Start of alignment in subject (database hit)
    10 send      End of alignment in subject (database hit)
    11 evalue    Expectation value (E-value)
    12 bitscore  Bit score
====== ========= ============================================

The BLAST+ tools can optionally output additional columns of information,
but this takes longer to calculate. Many commonly used extra columns are
included by selecting the extended tabular output. The extra columns are
included *after* the standard 12 columns. This is so that you can write
workflow filtering steps that accept either the 12 or 25 column tabular
BLAST output. Galaxy now uses this extended 25 column output by default.

====== ============= ===========================================
Column NCBI name     Description
------ ------------- -------------------------------------------
    13 sallseqid     All subject Seq-id(s), separated by a ';'
    14 score         Raw score
    15 nident        Number of identical matches
    16 positive      Number of positive-scoring matches
    17 gaps          Total number of gaps
    18 ppos          Percentage of positive-scoring matches
    19 qframe        Query frame
    20 sframe        Subject frame
    21 qseq          Aligned part of query sequence
    22 sseq          Aligned part of subject sequence
    23 qlen          Query sequence length
    24 slen          Subject sequence length
    25 salltitles    All subject title(s), separated by a '&lt;&gt;'
====== ============= ===========================================

The third option is to customise the tabular output by selecting which
columns you want, from the standard set of 12, the default set of 25,
or any of the additional columns BLAST+ offers (including species name).

The fourth option is BLAST XML output, which is designed to be parsed by
another program, and is understood by some Galaxy tools.

You can also choose several plain text or HTML output formats which are designed to be read by a person (not by another program).
The HTML versions use basic webpage formatting and can include links to the hits on the NCBI website.
The pairwise output (the default on the NCBI BLAST website) shows each match as a pairwise alignment with the query.
The two query anchored outputs show a multiple sequence alignment between the query and all the matches,
and differ in how insertions are shown (marked as insertions or with gap characters added to the other sequences).
    </token>
    <token name="@FASTA_WARNING@">.. class:: warningmark

You can also search against a FASTA file of subject (target)
sequences. This is *not* advised because it is slower (only one
CPU is used), but more importantly gives e-values for pairwise
searches (very small e-values which will look overly signficiant).
In most cases you should instead turn the other FASTA file into a
database first using *makeblastdb* and search against that.
    </token>
    <token name="@SEARCH_TIME_WARNING@">.. class:: warningmark

**Note**. Database searches may take a substantial amount of time.
For large input datasets it is advisable to allow overnight processing.  

-----
    </token>
</macros>