/**

@page file_formats  File Formats

@tableofcontents

@section      msa-formats   File formats for Multiple Sequence Alignments (MSA)

@subsection   msa-formats-clustal   ClustalW format

The @em ClustalW format is a relatively simple text file containing a single
multiple sequence alignment of DNA, RNA, or protein sequences. It was first used
as an output format for the @em clustalw programs, but nowadays it may also be
generated by various other sequence alignment tools. The specification is straight
forward:

- The first line starts with the words @verbatim CLUSTAL W @endverbatim or
  @verbatim CLUSTALW @endverbatim
- After the above header there is at least one empty line
- Finally, one or more blocks of sequence data are following, where each
  block is separated by at least one empty line
.
Each line in a blocks of sequence data consists of the sequence name followed by
the sequence symbols, separated by at least one whitespace character. Usually,
the length of a sequence in one block does not exceed 60 symbols. Optionally,
an additional whitespace separated cumulative residue count may follow the sequence
symbols. Optionally, a block may be followed by a line depicting the degree of
conservation of the respective alignment columns.

@note Sequence names and the sequences must not contain whitespace characters!
      Allowed gap symbols are the hyphen @em ("-"), and dot @em (".").

@warning  Please note that many programs that output this format tend to truncate
          the sequence names to a limited number of characters, for instance the
          first 15 characters. This can destroy the uniqueness of identifiers in
          your MSA.

Here is an example alignment in ClustalW format:
@verbinclude alignment_clustal.aln

@subsection   msa-formats-stockholm Stockholm 1.0 format

Here is an example alignment in Stockholm 1.0 format:
@verbinclude alignment_stockholm.stk

@see @ref wuss-notation on legal characters for the consensus secondary structure line @em SS_cons
and their interpretation

@subsection   msa-formats-fasta     FASTA (Pearson) format

@note Sequence names must not contain whitespace characters. Otherwise, the parts after
      the first whitespace will be dropped. The only allowed gap character is the hyphen
      @em ("-").

Here is an example alignment in FASTA format:
@verbinclude alignment_fasta.fa

@subsection   msa-formats-maf     MAF format

The multiple alignment format (MAF) is usually used to store multiple alignments on DNA level
between entire genomes. It consists of independent blocks of aligned sequences which are
annotated by their genomic location. Consequently, an MAF formatted MSA file may contain
multiple records. MAF files start with a line
@verbatim
##maf
@endverbatim
which is optionally extended by whitespace delimited key=value pairs. Lines starting with
the character ("#") are considered comments and usually ignored.

A MAF block starts with character ("a") at the beginning of a line, optionally followed
by whitespace delimited key=value pairs. The next lines start with character ("s") and
contain sequence information of the form
@verbatim
s src start size strand srcSize sequence
@endverbatim
where
- @em src is the name of the sequence source
- @em start is the start of the aligned region within the source (0-based)
- @em size is the length of the aligned region without gap characters
- @em strand is either ("+") or ("-"), depicting the location of the aligned
  region relative to the source
- @em srcSize is the size of the entire sequence source, e.g. the full chromosome
- @em sequence is the aligned sequence including gaps depicted by the hyphen ("-")
.

Here is an example alignment in MAF format (bluntly taken from the
<a href="https://cgwb.nci.nih.gov/FAQ/FAQformat.html#format5">UCSC Genome browser website</a>):
@verbinclude alignment_maf.maf


@section     constraint-formats   File formats to manipulate the RNA folding grammar
@subsection  constraint-formats-file Command Files

The RNAlib and many programs of the ViennaRNA Package can parse and apply data from
so-called command files. These commands may refer to structure constraints or even
extensions of the RNA folding grammar (such as @ref domains_up). Commands are given
as a line of whitespace delimited data fields. The syntax we use extends the constraint
definitions used in the 
<a href="http://mfold.rna.albany.edu/?q=mfold">mfold</a> /
<a href="http://mfold.rna.albany.edu/?q=DINAMelt/software">UNAfold</a> software, where
each line begins with a command character followed by a set of positions.\n
However, we introduce several new commands, and allow for an optional loop type context
specifier in form of a sequence of characters, and an orientation flag that enables one to force
a nucleotide to pair upstream, or downstream.

@subsubsection  constraint_commands Constraint commands
The following set of commands is recognized:
-  @p F @f$ \ldots @f$ Force
-  @p P @f$ \ldots @f$ Prohibit
-  @p C @f$ \ldots @f$ Conflicts/Context dependency
-  @p A @f$ \ldots @f$ Allow (for non-canonical pairs)
-  @p E @f$ \ldots @f$ Soft constraints for unpaired position(s), or base pair(s)

@subsubsection  domain_commands RNA folding grammar exensions
-  @p UD @f$ \ldots @f$ Add ligand binding using the @ref domains_up feature

@subsubsection  command_file_loop_types Specification of the loop type context
The optional loop type context specifier @p [LOOP] may be a combination of the following:
-  @p E @f$ \ldots @f$ Exterior loop
-  @p H @f$ \ldots @f$ Hairpin loop
-  @p I @f$ \ldots @f$ Interior loop
-  @p M @f$ \ldots @f$ Multibranch loop
-  @p A @f$ \ldots @f$ All loops

For structure constraints, we additionally allow one to address base pairs enclosed
by a particular kind of loop, which results in the specifier @p [WHERE] which consists
of @p [LOOP] plus the following character:
-  @p i @f$ \ldots @f$ enclosed pair of an Interior loop
-  @p m @f$ \ldots @f$ enclosed pair of a Multibranch loop

If no @p [LOOP] or @p [WHERE] flags are set, all contexts are considered (equivalent to @p A )

@subsubsection const_file_orientation Controlling the orientation of base pairing
For particular nucleotides that are forced to pair, the following @p [ORIENTATION] flags
may be used:
-  @p U @f$ \ldots @f$ Upstream
-  @p D @f$ \ldots @f$ Downstream

If no @p [ORIENTATION] flag is set, both directions are considered.

@subsubsection const_file_seq_coords Sequence coordinates
Sequence positions of nucleotides/base pairs are @f$ 1- @f$ based and consist of three
positions @f$ i @f$, @f$ j @f$, and @f$ k @f$. Alternativly, four positions may be provided
as a pair of two position ranges @f$ [i:j] @f$, and @f$ [k:l] @f$ using the '-' sign as
delimiter within each range, i.e. @f$ i-j @f$, and @f$ k-l @f$.

@subsubsection  const_file_syntax Valid constraint commands
Below are resulting general cases that are considered @em valid constraints:

-#  @b "Forcing a range of nucleotide positions to be paired":\n
    Syntax: @code F i 0 k [WHERE] [ORIENTATION] @endcode\n
    Description:\n
    Enforces the set of @f$ k @f$ consecutive nucleotides starting at
    position @f$ i @f$ to be paired. The optional loop type specifier @p [WHERE]
    allows to force them to appear as closing/enclosed pairs of certain types of loops.
-#  @b "Forcing a set of consecutive base pairs to form":\n
    Syntax: @verbatim F i j k [WHERE] @endverbatim\n
    Description:\n
    Enforces the base pairs @f$ (i,j), \ldots, (i+(k-1), j-(k-1)) @f$ to form.
    The optional loop type specifier @p [WHERE] allows to specify in which loop
    context the base pair must appear.
-#  @b "Prohibiting a range of nucleotide positions to be paired":\n
    Syntax: @verbatim P i 0 k [WHERE] @endverbatim\n
    Description:\n
    Prohibit a set of @f$ k @f$ consecutive nucleotides to participate
    in base pairing, i.e. make these positions unpaired. The optional loop type specifier
    @p [WHERE] allows to force the nucleotides to appear within the loop of
    specific types.
-#  @b "Probibiting a set of consecutive base pairs to form":\n
    Syntax: @verbatim P i j k [WHERE] @endverbatim\n
    Description:\n
    Probibit the base pairs @f$ (i,j), \ldots, (i+(k-1), j-(k-1)) @f$ to form.
    The optional loop type specifier @p [WHERE] allows to specify the type of
    loop they are disallowed to be the closing or an enclosed pair of.
-#  @b "Prohibiting two ranges of nucleotides to pair with each other":\n
    Syntax: @verbatim P i-j k-l [WHERE] @endverbatim
    Description:\n
    Prohibit any nucleotide @f$ p \in [i:j] @f$ to pair with any other nucleotide
    @f$ q \in [k:l] @f$. The optional loop type specifier @p [WHERE] allows to
    specify the type of loop they are disallowed to be the closing or an enclosed pair of.
-#  @b "Enforce a loop context for a range of nucleotide positions":\n
    Syntax: @verbatim C i 0 k [WHERE] @endverbatim
    Description:\n
    This command enforces nucleotides to be unpaired similar to @em prohibiting nucleotides to be paired,
    as described above. It too marks the corresponding nucleotides to be unpaired, however,
    the @p [WHERE] flag can be used to enforce specfic loop types the nucleotides must appear in.
-#  @b "Remove pairs that conflict with a set of consecutive base pairs":\n
    Syntax: @verbatim C i j k @endverbatim\n
    Description:\n
    Remove all base pairs that conflict with a set of consecutive base pairs
    @f$ (i,j), \ldots, (i+(k-1), j-(k-1)) @f$. Two base pairs @f$ (i,j) @f$ and @f$ (p,q) @f$
    conflict with each other if @f$ i < p < j < q @f$, or @f$ p < i < q < j @f$.
-#  @b "Allow a set of consecutive (non-canonical) base pairs to form":\n
    Syntax: @code A i j k [WHERE] @endcode\n
    Description:\n
    This command enables the formation of the consecutive base pairs
    @f$ (i,j), \ldots, (i+(k-1), j-(k-1)) @f$, no matter if they are @em canonical, or
    @em non-canonical. In contrast to the above @p F and @p W commands, which remove
    conflicting base pairs, the @p A command does not. Therefore, it may be used to
    allow @em non-canoncial base pair interactions. Since the RNAlib does not contain
    free energy contributions @f$ E_{ij} @f$ for non-canonical base pairs @f$ (i,j) @f$,
    they are scored as the @em maximum of similar, known contributions. In terms of a
    @em Nussinov like scoring function the free energy of non-canonical base pairs is therefore
    estimated as
    @f[ E_{ij} = \min \left[  \max_{(i,k) \in \{GC, CG, AU, UA, GU, UG\}} E_{ik}, \max_{(k,j) \in \{GC, CG, AU, UA, GU, UG\}} E_{kj} \right]. @f]
    The optional loop type specifier @p [WHERE] allows to specify in which loop
    context the base pair may appear.
-#  @b "Apply pseudo free energy to a range of unpaired nucleotide positions":\n
    Syntax: @code E i 0 k e @endcode\n
    Description:\n
    Use this command to apply a pseudo free energy of @f$ e @f$ to the set of @f$ k @f$
    consecutive nucleotides, starting at position @f$ i @f$. The pseudo free energy is
    applied only if these nucleotides are considered unpaired in the recursions, or evaluations,
    and is expected to be given in @f$ kcal / mol @f$.
-#  @b "Apply pseudo free energy to a set of consecutive base pairs":\n
    Syntax @code E i j k e @endcode\n
    Use this command to apply a pseudo free energy of @f$ e @f$ to the set of base pairs
    @f$ (i,j), \ldots, (i+(k-1), j-(k-1)) @f$. Energies are expected to be given in
    @f$ kcal / mol @f$.

@subsubsection  domains_syntax  Valid domain extensions commands

-#  @b "Add ligand binding to unpaired motif (a.k.a. unstructured domains)":\n
    Syntax: @code UD m e [LOOP] @endcode\n
    Description:\n
    Add ligand binding to unpaired sequence motif @f$ m @f$ (given in IUPAC format, capital letters)
    with binding energy @f$ e @f$ in particular loop type(s).\n
    Example:
    @code UD  AAA   -5.0    A@endcode\n
    The above example applies a binding free energy of @f$ -5 kcal/mol @f$ for a motif AAA
    that may be present in all loop types.

*/
