# Name of your program
package "RNAsubopt" # don't use package if you're using automake
purpose "calculate suboptimal secondary structures of RNAs"
#usage "RNAsubopt [options]\n"

# Version of your program
#version "2.0"   # don't use version if you're using automake


# command line options passed to gengetopt
args "--file-name=RNAsubopt_cmdl --include-getopt --default-optional --func-name=RNAsubopt_cmdline_parser --arg-struct-name=RNAsubopt_args_info"


description "reads RNA sequences from stdin and (in the default -e mode) calculates all suboptimal secondary\
 structures within a user defined energy range above the minimum free energy (mfe). It prints the suboptimal\
 structures in dot-bracket notation followed by the energy in kcal/mol to stdout. Be careful, the number of\
 structures returned grows exponentially with both sequence length and energy range.\n\nAlternatively, when\
 used with the -p option, RNAsubopt produces Boltzmann weighted samples of secondary structures.\n"

# Options

section "General Options"
sectiondesc="Below are command line options which alter the general behavior of this program\n"

option  "constraint"  C
"Calculate structures subject to constraints.\n"
details="The program reads first the\
 sequence, then a string containing constraints on the structure encoded with the symbols:\n\n. (no constraint\
 for this base)\n\n| (the corresponding base has to be paired\n\nx (the base is unpaired)\n\n< (base i is paired with\
 a base j>i)\n\n> (base i is paired with a base j<i)\n\nand matching brackets ( ) (base i pairs base j)\n\nWith the\
 exception of \"|\", constraints will disallow all pairs conflicting with the constraint. This is usually\
 sufficient to enforce the constraint, but occasionally a base may stay unpaired in spite of constraints. PF\
 folding ignores constraints of type \"|\".\n"
flag
off

option  "noconv"  -
"Do not automatically substitude nucleotide \"T\" with \"U\"\n"
flag
off

section "Algorithms"
sectiondesc="Select the algorithms which should be applied to the given RNA sequence.\n"

option  "deltaEnergy" e
"Compute suboptimal structures with energy in a certain range of the optimum (kcal/mol).\
 Default is calculation of mfe structure only.\n"
float
typestr="range"
optional

option  "deltaEnergyPost" -
"Only print structures with energy within range of the mfe after post reevaluation of energies.\n"
details="Useful in conjunction with -logML, -d1 or -d3: while the -e option specifies the range\
 before energies are re-evaluated, this option specifies the maximum energy after re-evaluation.\n"
float
typestr="range"
optional

option  "sorted"  s
"Sort the suboptimal structures by energy.\n"
details="Since the sort in is done in memory, this becomes impractical when the number of structures produced\
 goes into millions. In such cases better pipe the output through \"sort +1n\".\n"
flag
off

option "stochBT"  p
"Instead of producing all suboptimals in an energy range, produce a random sample of suboptimal structures,\
 drawn with probabilities equal to their Boltzmann weights via stochastic backtracking in the partition\
 function. The -e and -p options are mutually exclusive."
int
typestr="number"
optional

option  "pfScale" S
"In the calculation of the pf use scale*mfe as an estimate for the ensemble free energy (used to avoid\
 overflows). Needed by stochastic backtracking\n"
details="The default is 1.07, useful values are 1.0 to 1.2. Occasionally needed\
 for long sequences.\nYou can also recompile the program to use double precision (see the README file).\n"
double
typestr="scaling factor"
optional
hidden

option  "circ"    c
"Assume a circular (instead of linear) RNA molecule.\n"
flag
off

option  "dos" D
"Compute density of states instead of secondary structures\n"
details="This option enables the evaluation of the number of secondary structures in certain energy bands arround\
 the MFE.\n"
flag
off

option  "zuker" z
"Compute Zuker suboptimals instead of all suboptimal structures within an engery band arround the MFE\n."
flag
off

section "Model Details"

option  "temp"  T
"Rescale energy parameters to a temperature of temp C. Default is 37C.\n"
double
optional

option  "noTetra" 4
"Do not include special tabulated stabilizing energies for tri-, tetra- and hexaloop hairpins. Mostly for testing.\n"
flag
off

option  "dangles" d
"How to treat \"dangling end\" energies for bases adjacent to helices in free ends and multi-loops\n"
details="\nWith -d1 only unpaired bases can participate in at most one dangling end, this is the\
 default for mfe folding but unsupported for the partition function folding.\n\nWith -d2 this check is ignored,\
 dangling energies will be added for the bases adjacent to a helix on both sides in any case; this is the\
 default for partition function folding (-p).\nThe option -d0 ignores dangling ends altogether (mostly for\
 debugging).\nWith -d3 mfe folding will allow coaxial stacking of adjacent helices in multi-loops. At the\
 moment the implementation will not allow coaxial stacking of the two interior pairs in a loop of degree 3\
 and works only for mfe folding.\n\nNote that by default (as well as with -d1 and -d3) pf and mfe folding\
 treat dangling ends differently. Use -d2 in addition to -p to ensure that both algorithms use the same\
 energy model.\n"
int
default="2"
optional

option  "noLP"  -
"Produce structures without lonely pairs (helices of length 1).\n"
details="For partition function folding this only disallows pairs that can only occur isolated. Other\
 pairs may still occasionally occur as helices of length 1.\n"
flag
off

option  "noGU"  -
"Do not allow GU pairs\n"
flag
off

option  "noClosingGU" -
"Do not allow GU pairs at the end of helices\n"
flag
off

option  "logML" -
"Recalculate energies of structures using a logarithmic energy function for multi-loops before output."
details="This option does not effect structure generation, only the energies that are printed out.\
 Since logML lowers energies somewhat, some structures may be missing.\n"
flag
off

option  "paramFile" P
"Read energy parameters from paramfile, instead of using the default parameter set.\n"
details="A sample parameter file should accompany your distribution.\nSee the RNAlib\
 documentation for details on the file format.\n"
string
typestr="paramfile"
optional

option  "nsp" -
"Allow other pairs in addition to the usual AU,GC,and GU pairs.\n"
details="Its argument is a comma separated list of additionally allowed pairs. If the\
 first character is a \"-\" then AB will imply that AB and BA are allowed pairs.\ne.g.\
 RNAfold -nsp -GA  will allow GA and AG pairs. Nonstandard pairs are given 0 stacking\
 energy.\n"
string
optional
hidden

text    "References:\n\nS. Wuchty, W. Fontana, I. L. Hofacker and P. Schuster (1999) \"Complete\
 Suboptimal Folding of RNA and the Stability of Secondary Structures\", Biopolymers, 49, 145-165\n\n"

text    "Written by:\n\nIvo L Hofacker, Stefan Wuchty, Walter Fontana\n\n"
text    "Report bugs:\n\nIf in doubt our program is right, nature is at fault.\nComments should be sent to\
 rna@tbi.univie.ac.at.\n"