# Name of your program
package "RNAplot" # don't use package if you're using automake

purpose "Draw RNA Secondary Structures"

usage "RNAplot [OPTIONS] [<input0>] [<input1>]..."

# 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=RNAplot_cmdl --include-getopt --default-optional --unamed-opts --func-name=RNAplot_cmdline_parser --arg-struct-name=RNAplot_args_info"


description "The program reads (aligned) RNA sequences and structures in the format as produced by\
 RNAfold or Stockholm 1.0 and produces drawings of the secondary structure graph.\nCoordinates for\
 the structure graphs are produced using either E. Bruccoleri's naview routines, or a simple radial\
 layout method.\nFor aligned sequences and consensus structures (--msa option) the graph may be\
 annotated by covariance information. Additionally, a color-annotated EPS alignment figure can be\
 produced, similar to that obtained by RNAalifold and RNALalifold.\nIf the sequence was preceded by\
 a FASTA header, or if the multiple sequence alignment contains an ID field, these IDs will be taken\
 as names for the output file(s): \"name_ss.ps\" and \"name_aln.ps\". Otherwise \"rna.ps\" and \"aln.ps\"\
 will be used. This behavior may be over-ruled by explicitly setting a filename prefix using the --auto-id\
 option.\nExisting files of the same name will be overwritten.\n"

# Options

option  "verbose" v
"Be verbose.\n"
details="Lower the log level setting such that even INFO messages are passed through.\n\n"
flag
off


section "I/O Options"
sectiondesc="Command line options for input and output (pre-)processing\n\n"

option  "infile"  i
"Read a file instead of reading from stdin."
details="The default behavior of RNAplot is to read input from stdin or the file(s) that follow(s)\
 the RNAplot command. Using this parameter the user can specify input file names where data\
 is read from. Note, that any additional files supplied to RNAplot are still processed as well.\n"
string
typestr="<filename>"
multiple
optional

option  "msa"   a
"Input is multiple sequence alignment in Stockholm 1.0 format."
details="Using this flag indicates that the input is a multiple sequence alignment (MSA)\
 instead of (a) single sequence(s). Note, that only STOCKHOLM format allows one to specify\
 a consensus structure. Therefore, this is the only supported MSA format for now!\n"
flag
off

option  "mis"             -
"Output \"most informative sequence\" instead of simple consensus"
details="For each column of the alignment output this is the set of nucleotides with frequency\
 greater than average in IUPAC notation.\n"
flag
dependon="msa"
off

option  "jobs"  j
"Split batch input into jobs and start processing in parallel using multiple threads."
details="Default processing of input data is performed in a serial fashion, i.e. one sequence at\
 a time. Using this switch, a user can instead start the computation for many sequences in the\
 input in parallel. RNAplot will create as many parallel computation slots as specified and\
 assigns input sequences of the input file(s) to the available slots. Note, that this increases\
 memory consumption since input alignments have to be kept in memory until an empty compute slot\
 is available and each running job requires its own dynamic programming matrices. A value of 0\
 indicates to use as many parallel threads as computation cores are available.\n"
int
default="0"
typestr="number"
argoptional
optional

option  "output-format"   f
"Specify output file format."
details="Available formats are: Encapsulated PostScript ('eps'), Scalable Vector Graphics ('svg'),\
 Graph Meta Language ('gml'), and XRNA save file ('xrna'). Output filenames will end in\
 \".eps\" \".gml\" \".svg\" \".ss\", respectively.\n"
string
values="eps","svg","gml","xrna","ssv"
typestr="format"
default="eps"
optional


option  "pre"   -
"Add annotation macros to postscript file, and add the postscript code in \"string\" just\
 before the code to draw the structure. This is an easy way to add annotation."
string
typestr="string"
optional

option  "post"  -
"Same as --pre but in contrast to adding the annotation macros. E.g to mark position\
 15 with circle use --post=\"15 cmark\"."
string
typestr="string"
optional

option  "auto-id"  -
"Automatically generate an ID for each sequence.\n"
details="The default mode of RNAfold is to automatically determine an ID from the input sequence\
 data if the input file format allows to do that. Sequence IDs are usually given in the FASTA\
 header of input sequences. If this flag is active, RNAfold ignores any IDs retrieved from the\
 input and automatically generates an ID for each sequence. This ID consists of a prefix and an\
 increasing number. This flag can also be used to add a FASTA header to the output even if\
 the input has none.\n\n"
flag
off

option  "id-prefix" -
"Prefix for automatically generated IDs (as used in output file names).\n"
details="If this parameter is set, each sequence will be prefixed with the\
 provided string. Hence, the output files will obey the following naming\
 scheme: \"prefix_xxxx_ss.ps\" (secondary structure plot), \"prefix_xxxx_dp.ps\"\
 (dot-plot), \"prefix_xxxx_dp2.ps\" (stack probabilities), etc. where xxxx\
 is the sequence number. Note: Setting this parameter implies --auto-id.\n\n"
string
typestr="STRING"
default="sequence"
optional

option  "id-delim" -
"Change the delimiter between prefix and increasing number for automatically generated IDs (as used in output file names).\n"
details="This parameter can be used to change the default delimiter \"_\" between\
 the prefix string and the increasing number for automatically generated ID.\n\n"
string
typestr="CHAR"
default="_"
optional
hidden

option  "id-digits"  -
"Specify the number of digits of the counter in automatically generated alignment IDs.\n"
details="When alignments IDs are automatically generated, they receive an increasing number, starting\
 with 1. This number will always be left-padded by leading zeros, such that the number takes up a\
 certain width. Using this parameter, the width can be specified to the users need. We allow\
 numbers in the range [1:18]. This option implies --auto-id.\n\n"
int
default="4"
optional
hidden

option  "id-start"  -
"Specify the first number in automatically generated IDs.\n"
details="When sequence IDs are automatically generated, they receive an increasing number,\
 usually starting with 1. Using this parameter, the first number can be specified to the users\
 requirements. Note: negative numbers are not allowed.\nNote: Setting this parameter implies\
 to ignore any IDs retrieved from the input data, i.e. it activates the --auto-id flag.\n\n"
long
default="1"
optional
hidden

option  "filename-delim" -
"Change the delimiting character used in sanitized filenames.\n"
details="This parameter can be used to change the delimiting character used while\
 sanitizing filenames, i.e. replacing invalid characters. Note, that the default\
 delimiter ALWAYS is the first character of the \"ID delimiter\" as supplied through\
 the --id-delim option. If the delimiter is a whitespace character or empty, invalid\
 characters will be simply removed rather than substituted.\
 Currently, we regard the following characters as illegal for use in filenames:\
 backslash '\', slash '/', question mark '?', percent sign '%', asterisk '*', colon ':',\
 pipe symbol '|', double quote '\"', triangular brackets '<' and '>'.\n\n"
string
typestr="CHAR"
default="ID-delimiter"
optional
hidden

option  "filename-full" -
"Use full FASTA header to create filenames.\n"
details="This parameter can be used to deactivate the default behavior of limiting\
 output filenames to the first word of the sequence ID. Consider the following example:\
 An input with FASTA header '>NM_0001 Homo Sapiens some gene' usually produces output\
 files with the prefix \"NM_0001\" without the additional data available in the FASTA\
 header, e.g. \"NM_0001_ss.ps\" for secondary structure plots. With this flag set, no\
 truncation of the output filenames is done, i.e. output filenames receive the full\
 FASTA header data as prefixes. Note, however, that invalid characters (such as whitespace)\
 will be substituted by a delimiting character or simply removed, (see also the parameter\
 option --filename-delim).\n\n"
flag
off
hidden


option  "log-level" -
"Set log level threshold.\n"
details="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.\n\n"
int
typestr="level"
default="2"
hidden


option  "log-file" -
"Print log messages to a file instead of stderr.\n"
string
typestr="filename"
default="RNAplot.log"
argoptional
hidden


option  "log-time" -
"Include time stamp in log messages.\n\n"
flag
off
hidden


option  "log-call" -
"Include file and line of log calling function.\n\n"
flag
off
hidden


section "Plotting"
sectiondesc="Command line options for changing the default behavior of structure layout and pairing probability plots\n\n"

option  "covar"           -
"Annotate covariance of base pairs in consensus structure.\n\n"
flag
dependon="msa"
off

option  "covar-threshold" -
"Set the threshold of maximum counter examples for coloring consensus structure plot.\n"
details="Floating point numbers between 0 and 1 are treated as frequencies among all sequences\
in the alignment. All other will be truncated to integer and used as absolute number of counter
examples.\n\n"
float
optional
default="2"
hidden


option  "covar-min-sat" -
"Set the minimum saturation for coloring consensus structure plot.\n"
details="Floating point number >= 0 and smaller than 1.\n\n"
float
optional
default="0.2"
hidden


option  "aln"             -
"Produce a colored and structure annotated alignment in PostScript format in the file \"aln.ps\" in the\
 current directory.\n\n"
flag
dependon="msa"
off

option  "aln-EPS-cols"        -
"Number of columns in colored EPS alignment output.\n"
details="A value less than 1 indicates that the output should not be wrapped at all.\n\n"
int
default="60"
optional
dependon="msa"
hidden

option  "layout-type"  t
"Choose the plotting layout algorithm."
details="Select the layout algorithm that computes the nucleotide coordinates.\
 Currently, the following algorithms are available:\n\
 '0': simple radial layout\n\n\
 '1': Naview layout (Bruccoleri et al. 1988)\n\n\
 '2': circular layout\n\n\
 '3': RNAturtle (Wiegreffe et al. 2018)\n\n\
 '4': RNApuzzler (Wiegreffe et al. 2018)\n"
int
values="0","1","2","3","4"
default="1"
optional

option  "noOptimization"  -
"Disable the drawing space optimization of RNApuzzler.\n\n"
flag
off
hidden

option  "ignoreExteriorIntersections"  -
"Ignore intersections with the exterior loop within the RNA-tree.\n\n"
flag
off
hidden

option  "ignoreAncestorIntersections"  -
"Ignore ancestor intersections within the RNA-tree.\n\n"
flag
off
hidden

option  "ignoreSiblingIntersections"  -
"Ignore sibling intersections within the RNA-tree.\n\n"
flag
off
hidden

option  "allowFlipping"  -
"Allow flipping of exterior loop branches to resolve exterior branch intersections.\n\n"
flag
off
hidden


text    "\nIf in doubt our program is right, nature is at fault.\nComments should be sent to\
 rna@tbi.univie.ac.at.\n\n"
