Load configurations from file

--configure=file

Load a parameter set from a configuration file of options and option value pairs. This enables specifying (sets of) default parameters for mlocarna, which can still be modified by other options to mlocarna. Command line arguments always take precedence over this configuration. Options are specified as single entries per line; option value pairs, like option: value. Whitespace and '#'-prefixed comments are ignored.

Major alignment modes

By default, mlocarna performs progressive alignment, where the progressive alignment steps are computed by the pairwise aligner locarna based on sequences and dot plots (RNAfold -p); subsequently, partial alignmetns and their consensus dot plots.

--probabilistic

In probabilistic mode, mlocarna scores alignments using match probabilities that are computed by a partition function approach [tech. details: the probability computation is implemented in locarna_p; the probability-based scoring is performed by locarna in mea mode]. This enables mlocarna to consistency-transform the probabilities (option --consistency-transform) and to compute reliabilities. The tool reliability-profile.pl is provided to visualize reliability profiles. Reliabilities can also be used for iterating the alignment with reliably aligned base pairs as structural constraints (option --it-reliable-structure).

--sparse

Apply the sparsified alignment algorithm SPARSE for all pairwise alignments (instead of the default pairwise aligner locarna). SPARSE supports stronger sparsification for faster alignment computation and increases the structure prediction capabilities over locarna.

Controlling Output

--tgtdir

Target directory. All output files are written to this directory. Per default the target directory is generated from the input filename by replacing suffix fa by (or appending) out.

-v, --verbose

Turn on verbose ouput. Shows progress of computation of all-2-all pairwise alignments for guide tree computation; shows intermediary alignments during the progressive alignment computation.

--moreverbose

Be even more verbose: additionally shows parameters for the pairwise aligner; moreover, the calls and output of the RNA base pair probability computations as well as the pairwise aligner during progressive alignment.

-q, --quiet

Be quiet.

--keep-sequence-order

Preserve sequence order of the input in the final alignment. Affects output to stdout and results/result.aln.

--stockholm

Write STOCKHOLM files of all final and intermediate alignments (in addition to CLUSTALW files).

--consensus-structure

Type of consensus structures written to stockholm output (and screen in verbose modes) [alifold|mea|none] (default: none). This includes intermediate alignments of the progressive multiple alignment. If not explicitly specified othwise, the option alifold-consensus-dp implicitly sets this to alifold. Note that the alifold consenus of the final alignment is computed and printed, regardless of this option.

-w, --width=columns (120)

Output width for sequences in clustal-like and stockholm output; note that the clustalw standard format requires 60 or less.

--write-structure

Write guidance structure in output to stdout. This provides some insight into the influence of structure into the generated pairwise alignments. The guidance structure shows the base pairs 'predicted' by each pairwise locarna (or sparse) alignment. These structures should not be mistaken as predicted consensus structures of multiple alignments. Consensus structures can be more adequately derived from the multiple alignment. For this reason, mlocarna reports the consensus structure by RNAalifold.

Locality

--free-endgaps

Allow free endgaps. (Corresponds to pairwise locarna option --free-endgaps "++++".)

--free-endgaps-3

Allow free endgaps 3'.

--free-endgaps-5

Allow free endgaps 5'.

--sequ-local=bool (false)

Turns on/off sequence locality [def=off]. Sequence locality refers to the usual form of local alignment. If on, mlocarna bases all calculations on local pairwise alignments, which determin the best alignments of subsequences (disregarding dissimilar starts and ends). Note that truely local structure alignments as well as local multiple alignments are still a matter of research; so don't expect perfect results in all instances.

--struct-local=bool (false)

Turns on/off structure locality [def=off]. Structural locality enables skipping entire substructures in alignments. In pairwise alignments, this allows one exclusion of some subsequence in each loop; thus, guaranteeing that the (structure locally) aligned parts of the sequences are always connected w.r.t. the predicted structure but not necessarily consecutive in the sequence. Structure locality does not imply sequence locality, but rather the two concepts are orthogonal.

--penalized=score

Variant of sequence local alignment (cf. --sequ-local), where the specified penalty score is subtracted for each base in the local alignment. [Experimental]

Pairwise alignment and scoring

--indel=score (-150)

Score of each single base insertion or deletion.

--indel-opening=score (-750)

Score of opening an insertion or deletion, i.e. score for a consecutive run of deletions or insertions. Indel opening score and indel score define the affine scoring of gaps.

-m, --match=score (50)

Score of a base match (unless ribosum-based scoring)

-M, --mismatch=score (0)

Score of a base mismatch (unless ribosum-based scoring)

--use-ribosum=bool (true)

Use ribosum scores for scoring base matches and base pair matches; note that tau=0 suppresses any effect on the latter.

--ribosum-file=file

File specifying the Ribosum base and base-pair similarities. [default: use RIBOSUM85_60 without requiring a Ribosum file.]

-s, --struct-weight=score (200)

Maximum weight of one predicted arc, aka base pair. Note that this means that the maximum weight of an arc match is twice as high. The maximum weight is assigned to base pairs with (almost) probability 1 in the dot plot; less probable base pairs receive gradually degrading scores. The struct-weight factor balances the score contribution from structure to the score contribution from base similarity scores (e.g. ribosum scores).

-e, --exp-prob=prob

Expected probability of a base pair.

-t, --tau=factor (0)

Tau factor in percent. The tau factor controls the contribution of sequence-dependent scores to the score of arc matches.

-E, --exclusion=<score> (0)

Weight of an exclusion, i.e. an ommitted subsequence in a loop, which applies only to structural local alignment.

--stacking

Use stacking terms. In this case, stacked arcs are scored based on conditional probabilities (conditioned by their stacked inner arc) rather than unconditioned base pair probabilities. [Experimental]

--new-stacking

Use new stacking terms; cf. --stacking. These terms directly award bonuses to stacking. [Experimental]

Alignment heuristics

Several parameters are available to speed up the pairwise alignment computations heuristically. Choosing these parameters reasonably is necessary to achieve good trade-off between speed and accuracy, especially for large alignment instances.

-p, --min-prob=probability (0.001)

Minimum base pair / arc probability. Arc with lower probability in the input RNA structure ensembles are ignored.

-P, --tree-min-prob=probability

Minimal prob for constructing guide tree. This probability can be set separately for the all-2-all comparison for constructing the guide tree and the progressive/iterative alignment steps.

--max-bps-length-ratio=factor (0.0)

Maximal ratio of the number of base pairs divided by sequence length (default: no effect)

-D, --max-diff-am=difference

Maximal difference for lengths of matched arcs. Two arcs that have a higher difference of their lengths are ignored. This speeds up the alignment, since less arc comparisons (i.e. less DP matrices) have to be computed. [def: off/-1]

-d, --max-diff=difference

Maximal difference of the positions of any two bases that are considered to be aligned. Bases with higher difference are generally not aligned. This allows banding of the DP matrices and thus can result in high speed ups. Note that the semantic changes in the context of a reference alignment specified with max-diff-aln. Then, the difference to the reference alignment is restricted. [def: off/-1]

--max-diff-at-am=difference

Same restriction as max-diff but only at the ends of arcs in arc matches. [def: off/-1]

--min-trace-probability=probability

Minimal sequence alignment probability of potential traces (probability-based sequence alignment envelope) [default=1e-4, moderate filter].

--max-diff-aln=file

Computes "realignment" in the environment of the given reference alignment (file in clustalw format) by constraining the maximum difference to this reference (controlled by --max-diff). The input sequences (and their names) have to be identical to these alignment sequences; however the alignment is allowed to contain extra sequences, which are ignored. In combination with option --realign, the reference alignment is taken from the (main) input file. In this case, the 'file' argument should be '.', but is ignored (with warning) otherwise.

--max-diff-relax

Relax deviation constraints (cf. --max-diff-aln) in multiple aligmnent. This option is useful if the default strategy for realignment fails.

-a, --min-am-prob=probability (0.001)

Minimum arc-match probability (filters output of locarna-p)

-b, --min-bm-prob=probability (0.001)

Minimum base-match probability (filters output of locarna-p)

Low-level selection of pairwise alignment tools and options

--pw-aligner

Utilize the given tool for computing pairwise alignments (def=locarna).

--pw-aligner-p=tool

Utilize the given tool for computing partition function pairwise alignments (def=locarna_p).

--pw-aligner-options

Additional option string for the pairwise alignment tool (def="").

--pw-aligner-p-options

Additional option string for the partition function pairwise alignment tool (def="").

Controlling the guide tree construction

--treefile=file

File with guide tree in NEWICK format. The given tree is used as guide tree for the progressive alignment. This saves the calculation of pairwise all-vs-all similarities and construction of the guide tree.

--similarity-matrix=file

File with similarity matrix. The similarities in the matrix are used to construct the guide tree for the progressive alignment. This saves the calculation of pairwise all-vs-all similarities.

--score-lists

Construct the guide tree from pairwise scores in files scores* in the subdirectory scores of the target directory. The scores are typically precomputed, possibly in a distributed way, using --compute-pairwise-scores.

--compute-pairwise-scores=k/N

Compute only the pairwise alignments for the guide tree construction. Write scores to the file $tgtdir/scores/scores-$k and terminate. By computing only the k-th fraction of N parts, the option supports distributing the computation of the alignments. Before computing the pairwise scores, the dot plot files should be precomputed using --only-dps. (see also: --score-lists)

--graphkernel

Use the graphkernel for constructing the guide tree.

--svmsgdnspdk=program

Specify the svmsgdnspdk program (potentially including path). Default: use "svmsgdnspdk" in path.

--fasta2shrep=program

Program "fasta2shrep" for generating graphs from the input sequences for use with the graph kernel guide tree generation (potentially including path). Default: use "fasta2shrep_gspan.pl" in path.

--fasta2shrep-options=argument-string

Command line arguments for fasta2shrep. Default: "-wins 200 -shift 50 -stack -t 3 -M 3".

Controlling multiple alignment construction

--alifold-consensus-dp

Employs RNAalifold -p for generating consensus dotplot after each progressive alignment step. This replaces the default consensus dotplot computation, which averages over the input dot plots. This method should be used with care in combination with structural constraints, since it ignores them for all but the pairwise alignments of single sequences. Furthermore, note that it does not support --stacking or --new-stacking.

--max-alignment-size=size

Limit the maximum number of sequences that are aligned together by progressive alignment. This can be used to save unnecessary computations, when producing a clustering of the input RNAs rather than constructing a single multiple alignment. [default: no limit].

--local-progressive

Align only the subalignment of locally aligned subsequences in subsequent steps of the progressive multiple alignment. Note: this is only effective if local alignment is turned on. (Default for sequence local alignment; turn off by --global-progressive)

--global-progressive

Use alignments including "locality gaps" in subsequent steps of the progressive multiple alignment. Note: this is only effective if local alignment is turned on. (Opposite of --local-progressive)

--consistency-transformation

Apply probabilistic consistency transformation (only possible in probabilistic mode).

--iterate

Refine iteratively after progressive alignment. Currently, iterative refinement optimizes the SCI or RELIABILITY (not the locarna score)! Iterative refinement realigns all binary splits along the guide tree.

--iterations=number

Refine iteratively for given number of iterations (or stop at convergence).

--it-reliable-structure=number

Iterate alignment <num> times with reliable structure. This works only in probabilistic mode, when reliabilities can be computed.

Further options for probabilistic mode

--pf-only-basematch-probs

Use only base match probabilities (no base pair match probabilities).

--extended-pf

 Use extended precision for partition function values. This increases
 run-time and space (less than 2x), however enables handling
 significantly larger instances.
    

--quad-pf

 Use quad precision for partition function values. Even more precision
 than extended pf, but usually much slower (overrides extended-pf).
    

--pf-scale=<scale>

Scale of partition function; use for avoiding overflow in larger instances.

--fast-mea

Compute base match probabilities using Gotoh PF-algorithm.

--mea-alpha

Weight of unpaired probabilities in fast mea mode.

--mea-beta

Weight of base pair match contribution in probabilistic mode.

--mea-gamma

Reserved parameter for fast-mea mode.

--mea-gapcost

Turn on gap penalties in probabilistic/mea mode (default: off).

--write-probs / --no-write-probs

Write / don't write probabilities (of base matches and arc matches) to the target directory. Override by single options --(no-)write-bm-probs and --(no-)write-am-probs is possible. Use this to make the probability files available for post-processing. (default: don't write).

--write-bm-probs / --no-write-bm-probs

Don't write / Write base match probabilities to files in target dir (default: don't write).

--write-am-probs / --no-write-am-probs

Don't write / Write arc match probabilities to files in target dir (default: don't write).

Miscallaneous modes of operation

--realign

Realignment mode. In this mode, the input must be in clustal format and is interpreted as alignment of the input sequences; the sequences are obtained by removing all gap symbols. Moreover, the given alignment is set as reference alignment for --max-diff-aln. Structure and anchor constraints can be specified as consensus constraints in the input; constraints are specified as 'alignment strings' with names '#A1', '#S', or '#FS' for anchor, structure, or fixed structure constraints, respectively. Characters in the '#A1' anchor specification other than '-' and '.' constrain the aligned residues in the respective column to remain aligned (blanks are disallowed; annotations '#A2', '#A3', ... are ignored). The consensus structure constraint is equivalent to constraining each single sequence by the projection of the consensus constraint to the sequence (removing all base pairs with at least one gapped end).

--dp-cache=directory

Use directory <dir> as cache for dot plot or pp files (useful for avoiding multiple computation).

--only-dps

Compute only the pair probability files / dot plots, don't align (useful for filling the dp-cache).

--evaluate=file

Evaluate the given multiple alignment (clustalw aln format, or use --eval-fasta). This requires that probailities are already computed (mlocarna --probabilistic) and present in the target directory (--tgtdir).

--eval-fasta

Assume that alignment for evaluation (cf. --evaluate) is in fasta format.

Constraints

--anchor-constraints=<file>

Read anchor constraints from bed format specification.

Anchor constraints in four-column bed format specify positions of named anchor regions per sequence. The 'contig' names have to correspond to the fasta input sequence names. Anchor names must be unique per sequence and regions of the same name for different sequences must have the same length. This constrains the alignment to align all regions of the same name.

The specification of anchors via this option removes all anchor definitions that may be given directly in the fasta input file!

--ignore-constraints

Ignore all constraints (anchor and structure constraints) even if given.

Rna folding (RNAfold/RNAplfold)

--noLP / --LP

Disallow/Allow lonely pairs (default: Disallow).

--maxBPspan

Limit maximum span of base pairs (default off).

--relaxed-anchors

Relax semantics of anchor constraints (default off, meaning 'strict' semantics). For lexicographically ordered anchors, where each sequence is annotated with exactly the same names, both semantics are equivalent; thus, in this common case, the subtle differences can be ignored. In strict semantics, anchor names must be ordered lexicographically and can only be aligned in this order. In relaxed semantics, the only requirement is that equal anchor names are matched. Consequently, anchor names that don't occur in all sequences could be overwritten (if two names are assigned to the same position) or even introduce inconsistencies.

--plfold-span=span

Use RNAplfold with span.

--plfold-winsize=ws

Use RNAplfold with window of size ws (default=2*span).

--rnafold-parameter=<file>

Parameter file for RNAfold (RNAfold's -P option)

--rnafold-temperature=<temp>

Temperature for RNAfold (RNAfold's -T option)

--skip-pp

Skip computation of pair probs if the probabilities are already existing. Non-existing ones are still computed.

--no-bpp-precomputation

Switch off precomputation of base pair probabilties. Overwrite potentially existing input files. (compare skip-pp). For use with special pairwise aligners (e.g. locarna_n) that recompute the base pair probabilities at each invokation.

--in-loop-probabilities

Turn on precomputation of in loop probabilties. For use with special pairwise aligners (e.g. locarna_n) that use such probabilities.

Multithreading

--threads, --cpus=number

Use the given number of threads for computing pair probabilities and all-2-all alignments in parallel (multicore/processor support).

Be aware: mlocarna seems not to scale well for more than a few threads (often only 2 or 3). Using more threads is often detrimental, since it strongly increases memory consumption due to the current perl threading implementation. This unfortunate behavior seems hard to improve without major rewrite of the software.

Getting Help

--help

Brief help message

--man

Full documentation

The sequences are given in input file <file> in mfasta format. All results are written to a target directory <dir>. If the file tree is given, contained tree (in NEWICK-tree format) is used as guide tree for the progressive alignment. The final results are collected in <tgtdir>/results. The final multiple alignment is <tgtdir>/results/result.aln.

Calling mlocarna

[Note that the LocARNA distribution provides files of the following and other examples in Data/Examples.]

Sequences are typically given in plain fasta format like

    example.fa
    ----------------------------------------
    >fruA
    CCUCGAGGGGAACCCGAAAGGGACCCGAGAGG
    >fdhA
    CGCCACCCUGCGAACCCAAUAUAAAAUAAUACAAGGGAGCAGGUGGCG
    >vhuU
    AGCUCACAACCGAACCCAUUUGGGAGGUUGUGAGCU
    ----------------------------------------

To align these sequences, simply call

  mlocarna example.fa

Usually, it makes sense to set additional options; this is either done on the command line or via configuration files. A reasonable small configuration for global alignment of large instances would be

    short-example.cfg
    ----------------------------------------
    max-diff-am: 25
    max-diff:    60
    min-prob:    0.01
    plfold-span: 100
    indel:       -50
    indel-open:  -750
    threads:     8   # <- adapt to your hardware
    alifold-consensus-dp
    ----------------------------------------

To use it, call

    mlocarna --config short-example.cfg example.fa

which is equivalent to

    mlocarna --max-diff-am 25 --max-diff 60 --min-prob 0.01 \
             --indel -50 --indel-open -750 \
             --plfold-span 100 --threads 8 --alifold-consensus-dp \
             example.fa

For probabilistic alignment with consistency transformation, call

  mlocarna --probabilistic --consistency-transform example.fa

In both cases, mlocarna writes the main results to stdout and more detailed results to the target directory example.out. The results directory is overwritten if it exists already. To avoid this, one can specify the target directory (--tgtdir).

Use of constraints

Mlocarna supports structure constraints for folding and anchor constraints for alignment. Both types of constraints can be specified in extension of the standard fasta format via 'constraint lines'. Fasta-ish input with constraints looks like this

    example-w-constraints.fa
    ----------------------------------------
    >A
    GACCCUGGGAACAUUAACUACUCUCGUUGGUGAUAAGGAACA
    ..((.(....xxxxxx...................))).xxx #S
    ..........000000.......................111 #1
    ..........123456.......................123 #2
    >B
    ACGGAGGGAAAGCAAGCCUUCUGCGACA
    .(((....xxxxxx.......))).xxx #S
    ........000000...........111 #1
    ........123456...........123 #2
    ----------------------------------------

The same anchor constraints (like by the lines tagged #1, #2) can alternatively be specified in bed format by the entries

    example-anchors.bed
    ----------------------------------------
    A   10      16      first_box
    B   8       14      first_box
    A   39      42      ACA-box
    B   25      28      ACA-box
    ----------------------------------------

where anchor regions (boxes) have arbitrary but matching names and contig/sequence names correspond to the sequence names of the fasta(-like) input.

Given, e.g.

    example-wo-anchors.fa
    ----------------------------------------
    >A
    GACCCUGGGAACAUUAACUACUCUCGUUGGUGAUAAGGAACA
    ..((.(....xxxxxx...................))).xxx #S
    >B
    ACGGAGGGAAAGCAAGCCUUCUGCGACA
    .(((....xxxxxx.......))).xxx #S
    ----------------------------------------

one calls

  mlocarna --anchor-constraints example-anchors.bed  example-wo-anchors.fa

Realignment

In realignment mode (option --realign), mlocarna is called with an input alignment in clustal format, e.g.

  mlocarna --realign example-realign.aln

This allows to define constraints as 'consensus constraints' in the input, e.g.

    example-realign.aln
    ----------------------------------------
    CLUSTAL W
    fruA               --CCUCGAGGGGAACCCGAA-------------AGGGACCCGAGAGG--
    vhuU               AGCUCACAACCGAACCCAUU-------------UGGGAGGUUGUGAGCU
    fdhA               CGCCACCCUGCGAACCCAAUAUAAAAUAAUACAAGGGAGCAG-GUGGCG
    #A1                ..*...........CCC.............................5..
    #S                 ((((((.((((...(((.................))).)))).))))))
    ----------------------------------------

Note that anchor names are arbitrary and the consensus structure is 'projected' to the single sequences. Moreover, the input alignment can be used as reference for fast limited realignment, e.g. call to realign in distance 5 of the reference alignment:

  mlocarna --realign example-realign.aln --max-diff 5 --max-diff-aln .