comparison cmbuild.xml @ 0:652f9d550531 draft

author bgruening
date Tue, 22 Apr 2014 13:56:22 -0400
children fac157e22e1b
equal deleted inserted replaced
-1:000000000000 0:652f9d550531
1 <tool id="infernal_cmbuild" name="Build covariance models" version="">
2 <description>from sequence alignments (cmbuild)</description>
3 <parallelism method="multi" split_inputs="alignment_infile" split_mode="to_size" split_size="10" shared_inputs="" merge_outputs="cmfile_outfile"></parallelism>
4 <requirements>
5 <requirement type="package">infernal</requirement>
6 <requirement type="package" version="1.1">infernal</requirement>
7 <requirement type="package" version="8.21">gnu_coreutils</requirement>
8 </requirements>
9 <command>
10 cmbuild
11 #if $is_summery_output:
12 -o $summary_outfile
13 #end if
15 ## to many outputs, is that one really needed?
16 ##-O $annotated_source_alignment_outfile
18 $model_construction_opts.model_construction_opts_selector
19 #if $model_construction_opts.model_construction_opts_selector == '--fast':
20 --symfrac $model_construction_opts.symfrac
21 #end if
23 $noss
25 $relative_weights_opts.relative_weights_opts_selector
26 #if $relative_weights_opts.relative_weights_opts_selector == '--wblosum':
27 --wid $relative_weights_opts.wid
28 #end if
30 $effective_opts.effective_opts_selector
31 #if str($effective_opts.effective_opts_selector) == '--eent':
32 --ere $effective_opts.ere
33 --eminseq $effective_opts.eminseq
34 --ehmmre $effective_opts.ehmmre
35 --eset $effective_opts.eset
36 #end if
38 #if str($refining_opts.refining_opts_selector) == '--refine':
39 #if $refining_opts.refine_output:
40 --refine $refined_multiple_alignment_output
41 #else:
42 --refine /dev/null
43 #end if
45 $l
46 $refining_opts.gibbs_opts.gibbs_opts_selector
48 #if str($refining_opts.gibbs_opts.gibbs_opts_selector) == '--gibbs':
49 $refining_opts.gibbs_opts.random_seed
50 #end if
52 $notrunc
53 $cyk
54 #end if
56 $cmfile_outfile
57 $alignment_infile
59 </command>
60 <inputs>
61 <!-- Stockholm or SELEX
62 SELEX is defined in EMBOSS datatypes
63 -->
64 <param name="alignment_infile" type="data" format="stockholm,selex" label="Sequence database"/>
66 <conditional name="model_construction_opts">
67 <param name="model_construction_opts_selector" type="select" label="These options control how consensus columns are defined in an alignment" help="">
68 <option value="--fast" selected="true">automatic (--fast)</option>
69 <option value="--hand">user defined (--hand)</option>
70 </param>
71 <when value="--fast">
72 <param name="symfrac" type="float" value="0.5" size="5"
73 label="Define the residue fraction threshold necessary to define a consensus (--symfrac)" help=""/>
74 </when>
75 <when value="--hand"/>
76 </conditional>
78 <param name="noss" truevalue="--noss" falsevalue="" checked="False" type="boolean"
79 label="Ignore the secondary structure annotation, if any, in your multiple alignment file (--noss)" help=""/>
81 <conditional name="relative_weights_opts">
82 <param name="relative_weights_opts_selector" type="select" label="Options controlling relative weights" help="">
83 <option value="--wpb" selected="true">Henikoff (--wgb)</option>
84 <option value="--wgsc">Gerstein/Sonnhammer/Chothia (--wgsc)</option>
85 <option value="--wnone">no sequence weighting (--wnone)</option>
86 <option value="--wgiven">Sequence weight from given in input file (--wgiven)</option>
87 <option value="--wblosum">BLOSUM filtering algorithm (--wblosum)</option>
88 </param>
89 <when value="--wpb"/>
90 <when value="--wgsc"/>
91 <when value="--wnone"/>
92 <when value="--wgiven"/>
93 <when value="--wblosum">
94 <param name="wid" type="float" value="0.5" size="5"
95 label="Percent identity for clustering the alignment (--wid)" help=""/>
96 </when>
97 </conditional>
100 <conditional name="effective_opts">
101 <param name="effective_opts_selector" type="select" label="Options controlling effective sequence number" help="">
102 <option value="--eent" selected="true">entropy weighting strategy (--eent)</option>
103 <option value="--enone">Turn off the entropy weighting strategy (--enone)</option>
104 </param>
105 <when value="--enone"/>
106 <when value="--eent">
107 <param name="ere" type="float" value="0.59" size="5"
108 label="Set the target mean match state relative entropy (--ere)" help=""/>
110 <param name="eminseq" type="integer" value="" size="5"
111 label="Define the minimum allowed effective sequence number (--eminseq)" help=""/>
113 <param name="ehmmre" type="float" value="" size="5"
114 label="Set the target HMM mean match state relative entropy (--ehmmre)" help=""/>
116 <param name="eset" type="integer" value="" size="5"
117 label="Set the effective sequence number for entropy weighting (--eset)" help=""/>
118 </when>
119 </conditional>
122 <conditional name="refining_opts">
123 <param name="refining_opts_selector" type="select" label="Options for refining the input alignment" help="">
124 <option value="" selected="true">No refinement</option>
125 <option value="--refine">refine the input alignment</option>
126 </param>
127 <when value=""/>
128 <when value="--refine">
130 <conditional name="gibbs_opts">
131 <param name="gibbs_opts_selector" type="select" label="refinement mode" help="">
132 <option value="" selected="true">expectation-maximization (EM)</option>
133 <option value="--gibbs">Gibbs sampling</option>
134 </param>
135 <when value=""/>
136 <when value="--gibbs">
137 <param name="random_seed" type="integer" value="0" label="Randam Seed" help="" />
138 </when>
139 </conditional>
141 <param name="l" truevalue="-l" falsevalue="" checked="False" type="boolean"
142 label="Turn on the local alignment algorithm" help="... which allows the alignment to span two or more subsequences if necessary"/>
144 <param name="notrunc" truevalue="--notrunc" falsevalue="" checked="False" type="boolean"
145 label="Turn off the truncated alignment algorithm" help=""/>
147 <param name="cyk" type="select" label="Options for refining the input alignment" help="">
148 <option value="" selected="true">optimal accuracy algorithm</option>
149 <option value="--cyk">align with the CYK algorithm</option>
150 </param>
152 <param name="refine_output" truevalue="" falsevalue="" checked="False" type="boolean"
153 label="Output the refined alignment file as it is used to build the covariance model" help=""/>
155 </when>
156 </conditional>
159 <param name="is_summery_output" truevalue="" falsevalue="" checked="False" type="boolean"
160 label="Output a summery file?" help=""/>
162 </inputs>
163 <outputs>
165 <data format="text" name="summary_outfile" label="cmbuild summary on ${on_string}">
166 <filter>is_summery_output is True</filter>
167 </data>
168 <!--<data format="stockholm" name="annotated_source_alignment_outfile" label="Annotated alignment from ${on_string}"/>-->
169 <data format="cm" name="cmfile_outfile" label="Covariance models from ${on_string}"/>
171 <data format="stockholm" name="refined_multiple_alignment_output" label="refined alignment file of ${on_string}">
172 <filter>
173 ((
174 refining_opts['refining_opts_selector'] == "--refine" and
175 refining_opts['refine_output'] is True
176 ))
177 </filter>
178 </data>
180 </outputs>
181 <help>
184 **What it does**
186 For each multiple sequence alignment build a covariance model.
187 The alignment file must be in Stockholm or SELEX format, and must contain consensus secondary structure annotation.
188 cmbuild uses the consensus structure to determine the architecture of the CM.
190 In addition to writing CM(s) to CMFILE_OUT, cmbuild also outputs a single line for each model created to stdout. Each
191 line has the following fields: ”aln”: the index of the alignment used to build the CM; ”idx”: the index of the CM in the
192 CMFILE_OUT; ”name”: the name of the CM; ”nseq”: the number of sequences in the alignment used to build the CM;
193 ”eff nseq”: the effective number of sequences used to build the model; ”alen”: the length of the alignment used to build
194 the CM; ”clen”: the number of columns from the alignment defined as consensus (match) columns; ”bps”: the number
195 of basepairs in the CM; ”bifs”: the number of bifurcations in the CM; ”rel entropy: CM”: the total relative entropy of the
196 model divided by the number of consensus columns; ”rel entropy: HMM”: the total relative entropy of the model ignoring
197 secondary structure divided by the number of consensus columns. ”description”: description of the model/alignment.
200 Options controlling model construction
201 --------------------------------------
203 These options control how consensus columns are defined in an alignment.
205 * --fast Define consensus columns automatically as those that have a fraction >= symfrac of residues as opposed to gaps. (See below for the --symfrac option.) This is the default.
206 * --hand Use reference coordinate annotation (#=GC RF line, in Stockholm) to determine which columns are consensus, and which are inserts. Any non-gap character indicates a consensus column. (For example, mark consensus columns with ”x”, and insert columns with ”.”.)
207 * --symfrac Define the residue fraction threshold necessary to define a consensus column when not using --hand. The default is 0.5. The symbol fraction in each column is calculated after taking relative sequence weighting into account. Setting this to 0.0 means that every alignment column will be assigned as consensus, which may be useful in some cases. Setting it to 1.0 means that only columns that include 0 gaps will be assigned as consensus.
208 * --noss Ignore the secondary structure annotation, if any, in MSA-Infile and build a CM with zero basepairs. This model will be similar to a profile HMM and the cmsearch and cmscan programs will use HMM algorithms which are faster than CM ones for this model. Additionally, a zero basepair model need not be calibrated with cmcalibrate prior to running cmsearch with it. The --noss option must be used if there is no secondary structure annotation in MSA-Infile.
211 Options controlling relative weights
212 ------------------------------------
214 cmbuild uses an ad hoc sequence weighting algorithm to downweight closely related sequences and upweight distantly
215 related ones. This has the effect of making models less biased by uneven phylogenetic representation. For example,
216 two identical sequences would typically each receive half the weight that one sequence would. These options control
217 which algorithm gets used.
219 * --wpb Use the Henikoff position-based sequence weighting scheme [Henikoff and Henikoff, J. Mol. Biol. 243:574, 1994]. This is the default.
220 * --wgsc Use the Gerstein/Sonnhammer/Chothia weighting algorithm [Gerstein et al, J. Mol. Biol. 235:1067, 1994].
221 * --wnone Turn sequence weighting off; e.g. explicitly set all sequence weights to 1.0.
222 * --wgiven Use sequence weights as given in annotation in the input alignment file. If no weights were given, assume they are all 1.0. The default is to determine new sequence weights by the Gerstein/Sonnhammer/Chothia algorithm, ignoring any annotated weights.
223 * --wblosum Use the BLOSUM filtering algorithm to weight the sequences, instead of the default GSC weighting. Cluster the sequences at a given percentage identity (see --wid); assign each cluster a total weight of 1.0, distributed equally amongst the members of that cluster.
224 * --wid Controls the behavior of the --wblosum weighting option by setting the percent identity for clustering the alignment.
227 Options controlling effective sequence number
228 ---------------------------------------------
230 After relative weights are determined, they are normalized to sum to a total effective sequence number, eff nseq. This
231 number may be the actual number of sequences in the alignment, but it is almost always smaller than that. The default
232 entropy weighting method (--eent) reduces the effective sequence number to reduce the information content (relative
233 entropy, or average expected score on true homologs) per consensus position. The target relative entropy is controlled
234 by a two-parameter function, where the two parameters are settable with --ere and --esigma.
236 * --eent Use the entropy weighting strategy to determine the effective sequence number that gives a target mean match state relative entropy. This option is the default, and can be turned off with --enone. The default target mean match state relative entropy is 0.59 bits for models with at least 1 basepair and 0.38 bits for models with zero basepairs, but changed with --ere. The default of 0.59 or 0.38 bits is automatically changed if the total relative entropy of the model (summed match state relative entropy) is less than a cutoff, which is is 6.0 bits by default, but can be changed with the expert, undocumented --eX option. If you really want to play with that option, consult the source code.
237 * --enone Turn off the entropy weighting strategy. The effective sequence number is just the number of sequences in the alignment.
238 * --ere Set the target mean match state relative entropy. By default the target relative entropy per match position is 0.59 bits for models with at least 1 basepair and 0.38 for models with zero basepairs.
239 * --eminseq Define the minimum allowed effective sequence number.
240 * --ehmmre Set the target HMM mean match state relative entropy. Entropy for basepairing match states is calculated using marginalized basepair emission probabilities.
241 * --eset Set the effective sequence number for entropy weighting.
245 Options for refining the input alignment
246 ----------------------------------------
248 * --refine Attempt to refine the alignment before building the CM using expectation-maximization (EM). A CM is first built from the initial alignment as usual. Then, the sequences in the alignment are realigned optimally (with the HMM banded CYK algorithm, optimal means optimal given the bands) to the CM, and a new CM is built from the resulting alignment. The sequences are then realigned to the new CM, and a new CM is built from that alignment. This is continued until convergence, specifically when the alignments for two successive iterations are not significantly different (the summed bit scores of all the sequences in the alignment changes less than 1% between two successive iterations).
249 * -l Turn on the local alignment algorithm, which allows 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. The default is to globally align the query model to the target sequences.
250 * --gibbs Modifies the behavior of --refine so Gibbs sampling is used instead of EM. The difference is that during the alignment stage the alignment is not necessarily optimal, instead an alignment (parsetree) for each sequences is sampled from the posterior distribution of alignments as determined by the Inside algorithm. Due to this sampling step --gibbs is non- deterministic, so different runs with the same alignment may yield different results. This is not true when --refine is used without the --gibbs option, in which case the final alignment and CM will always be the same. When --gibbs is enabled, the --seed "number" option can be used to seed the random number generator predictably, making the results reproducible. The goal of the --gibbs option is to help expert RNA alignment curators refine structural alignments by allowing them to observe alternative high scoring alignments.
251 * --seed Seed the random number generator with an integer >= 0. This option can only be used in combination with --gibbs. If the given number is nonzero, stochastic sampling of alignments will be reproducible; the same command will give the same results. If the given number is 0, the random number generator is seeded arbitrarily, and stochastic samplings may vary from run to run of the same command. The default seed is 0.
252 * --cyk With --refine, align with the CYK algorithm. By default the optimal accuracy algorithm is used. There is more information on this in the cmalign manual page.
253 * --notrunc With --refine, turn off the truncated alignment algorithm. There is more information on this in the cmalign manual page.
256 For further questions please refere to the Infernal Userguide_.
258 .. _Userguide:
261 How do I cite Infernal?
262 -----------------------
264 The recommended citation for using Infernal 1.1 is E. P. Nawrocki and S. R. Eddy, Infernal 1.1: 100-fold faster RNA homology searches , Bioinformatics 29:2933-2935 (2013).
266 **Galaxy Wrapper Author**::
268 * Bjoern Gruening, University of Freiburg
270 </help>
271 </tool>