###########
RNAdistance
###########

:program:`RNAdistance` - manual page for RNAdistance 2.7.2

Synopsis
--------

.. code:: bash

    RNAdistance [OPTION]...

DESCRIPTION
-----------

RNAdistance 2.7.2

Calculate distances between RNA secondary structures

This program reads RNA secondary structures from stdin and calculates one or
more measures for their dissimilarity, based on tree or string editing
(alignment). In addition it calculates a "base pair distance" given by the
number of base pairs present in one structure, but not the other. For
structures of different length base pair distance is not recommended.


RNAdistance accepts structures in bracket format, where matching brackets
symbolize base pairs and unpaired bases are represented by a dot ``.``,
or coarse grained representations where hairpins, interior loops,
bulges, multiloops, stacks and external bases are represented by
(H), (I), (B), (M), (S), and (E), respectively. These can be optionally
weighted. Full structures can be represented in the same fashion using
the identifiers (U) and (P) for unpaired and paired bases, respectively.
We call this the HIT representation (you don't want to know what this means).
For example the following structure consists of 2 hairpins joined by
a multiloop:

.. code::

    .((..(((...)))..((..)))).       full structure (usual format);
    (U)((U2)((U3)P3)(U2)((U2)P2)P2) HIT structure;
    ((H)(H)M)  or
    ((((H)S)((H)S)M)S)              coarse grained structure;
    (((((H3)S3)((H2)S2)M4)S2)E2)    weighted coarse grained.
    


The program will continue to read new structures until a line consisting
of the single character ``@`` or an end of file condition is encountered. Input
lines neither containing a valid structure nor starting with ``>`` are ignored.

.. option:: -h, --help

    Print help and exit

.. option:: --detailed-help

    Print help, including all details and hidden options, and exit

.. option:: --full-help

    Print help, including hidden options, and exit

.. option:: -V, --version

    Print version and exit

.. option:: -v, --verbose

    Be verbose. *(default=off)*


    Lower the log level setting such that even INFO messages are passed through.

.. option:: -D, --distance=fhwcFHWCP

    Specify the distance representation to be used in calculations.


    *(default="f")*


    Use the full, HIT, weighted coarse, or coarse representation to calculate the
    distance. Capital letters indicate string alignment otherwise tree editing is
    used.
    Any combination of distances can bespecified.

.. option:: -X, --compare=p|m|f|c

    Specify the comparison directive. *(default="p")*


    Possible arguments for this option are: :option:`-Xp` compare the structures pairwise
    (p), i.e. first with 2nd, third with 4th etc.
    :option:`-Xm` calculate the distance matrix between all structures. The output is
    formatted as a lower triangle matrix.
    :option:`-Xf` compare each structure to the first one.
    :option:`-Xc` compare continuously, that is i-th with (i+1)th structure.

.. option:: -S, --shapiro

    Use the Bruce Shapiro's cost matrix for comparing coarse structures.


    *(default=off)*

.. option:: -B, --backtrack[=<filename>]

    Print an "alignment" with gaps of the structures, to show matching substructures. The aligned structures are written to <filename>, if specified.


    *(default="none")*


    If <filename> is not specified, the output is written to stdout, unless the
    :option:`-Xm` option is set in which case "backtrack.file" is used.

.. option:: --log-level=level

    Set log level threshold. *(default="2")*


    By default, any log messages are filtered such that only warnings (level 2)
    or errors (level 3) are printed. This setting allows for specifying the log
    level threshold, where higher values result in fewer information. Log-level 5
    turns off all messages, even errors and other critical information.

.. option:: --log-file[=filename]

    Print log messages to a file instead of stderr. *(default="RNAdist.log")*

.. option:: --log-time

    Include time stamp in log messages.


    *(default=off)*

.. option:: --log-call

    Include file and line of log calling function.


    *(default=off)*

REFERENCES
----------

*If you use this program in your work you might want to cite:*

R. Lorenz, S.H. Bernhart, C. Hoener zu Siederdissen, H. Tafer, C. Flamm, P.F. Stadler and I.L. Hofacker (2011),
"ViennaRNA Package 2.0",
Algorithms for Molecular Biology: 6:26

I.L. Hofacker, W. Fontana, P.F. Stadler, S. Bonhoeffer, M. Tacker, P. Schuster (1994),
"Fast Folding and Comparison of RNA Secondary Structures",
Monatshefte f. Chemie: 125, pp 167-188

R. Lorenz, I.L. Hofacker, P.F. Stadler (2016),
"RNA folding with hard and soft constraints",
Algorithms for Molecular Biology 11:1 pp 1-13

B.A. Shapiro (1988),
"An algorithm for comparing multiple RNA secondary structures"
CABIOS: 4, pp 381-393

B.A. Shapiro, K. Zhang (1990),
"Comparing multiple RNA secondary structures using tree comparison",
CABIOS: 6, pp 309-318

W. Fontana, D.A.M. Konings, P.F. Stadler and P. Schuster P (1993),
"Statistics of RNA secondary structures",
Biopolymers: 33, pp 1389-1404

*The energy parameters are taken from:*

D.H. Mathews, M.D. Disney, D. Matthew, J.L. Childs, S.J. Schroeder, J. Susan, M. Zuker, D.H. Turner (2004),
"Incorporating chemical modification constraints into a dynamic programming algorithm for prediction of RNA secondary structure",
Proc. Natl. Acad. Sci. USA: 101, pp 7287-7292

D.H Turner, D.H. Mathews (2009),
"NNDB: The nearest neighbor parameter database for predicting stability of nucleic acid secondary structure",
Nucleic Acids Research: 38, pp 280-282

AUTHOR
------


Walter Fontana, Ivo L Hofacker, Peter F Stadler

REPORTING BUGS
--------------


If in doubt our program is right, nature is at fault.
Comments should be sent to rna@tbi.univie.ac.at.