RNAlib-2.2.0-RC2
Utilities
+ Collaboration diagram for Utilities:

Modules

 Parsing, Converting, and Comparing - Functions to Manipulate Secondary Structures
 
 Functions to Read/Write several File Formats for RNA Sequences, Structures, and Alignments
 
 Functions for Creating RNA Secondary Structures Plots, Dot-Plots, and More
 

Files

file  utils.h
 General utility- and helper-functions used throughout the ViennaRNA Package.
 

Macros

#define VRNA_INPUT_ERROR   1U
 Output flag of get_input_line(): "An ERROR has occured, maybe EOF".
 
#define VRNA_INPUT_QUIT   2U
 Output flag of get_input_line(): "the user requested quitting the program".
 
#define VRNA_INPUT_MISC   4U
 Output flag of get_input_line(): "something was read".
 
#define VRNA_INPUT_FASTA_HEADER   8U
 Input/Output flag of get_input_line():
if used as input option this tells get_input_line() that the data to be read should comply with the FASTA format. More...
 
#define VRNA_INPUT_CONSTRAINT   32U
 Input flag for get_input_line():
Tell get_input_line() that we assume to read a structure constraint. More...
 
#define VRNA_INPUT_NO_TRUNCATION   256U
 Input switch for get_input_line(): "do not trunkate the line by eliminating white spaces at end of line".
 
#define VRNA_INPUT_NO_REST   512U
 Input switch for vrna_read_fasta_record(): "do fill rest array".
 
#define VRNA_INPUT_NO_SPAN   1024U
 Input switch for vrna_read_fasta_record(): "never allow data to span more than one line".
 
#define VRNA_INPUT_NOSKIP_BLANK_LINES   2048U
 Input switch for vrna_read_fasta_record(): "do not skip empty lines".
 
#define VRNA_INPUT_BLANK_LINE   4096U
 Output flag for vrna_read_fasta_record(): "read an empty line".
 
#define VRNA_INPUT_NOSKIP_COMMENTS   128U
 
#define VRNA_INPUT_COMMENT   8192U
 Output flag for vrna_read_fasta_record(): "read a comment".
 
#define VRNA_OPTION_MULTILINE   32U
 Tell a function that an input is assumed to span several lines. More...
 
#define MIN2(A, B)   ((A) < (B) ? (A) : (B))
 Get the minimum of two comparable values.
 
#define MAX2(A, B)   ((A) > (B) ? (A) : (B))
 Get the maximum of two comparable values.
 
#define MIN3(A, B, C)   (MIN2( (MIN2((A),(B))) ,(C)))
 Get the minimum of three comparable values.
 
#define MAX3(A, B, C)   (MAX2( (MAX2((A),(B))) ,(C)))
 Get the maximum of three comparable values.
 
#define XSTR(s)   STR(s)
 Stringify a macro after expansion.
 
#define STR(s)   #s
 Stringify a macro argument.
 
#define FILENAME_MAX_LENGTH   80
 Maximum length of filenames that are generated by our programs. More...
 
#define FILENAME_ID_LENGTH   42
 Maximum length of id taken from fasta header for filename generation. More...
 

Functions

void * vrna_alloc (unsigned size)
 Allocate space safely. More...
 
void * vrna_realloc (void *p, unsigned size)
 Reallocate space safely. More...
 
void vrna_message_error (const char message[])
 Die with an error message. More...
 
void vrna_message_warning (const char message[])
 Print a warning message. More...
 
void vrna_init_rand (void)
 Initialize seed for random number generator.
 
double vrna_urn (void)
 get a random number from [0..1] More...
 
int vrna_int_urn (int from, int to)
 Generates a pseudo random integer in a specified range. More...
 
void vrna_file_copy (FILE *from, FILE *to)
 Inefficient `cp'.
 
char * vrna_time_stamp (void)
 Get a timestamp. More...
 
char * vrna_random_string (int l, const char symbols[])
 Create a random string using characters from a specified symbol set. More...
 
int vrna_hamming_distance (const char *s1, const char *s2)
 Calculate hamming distance between two sequences. More...
 
int vrna_hamming_distance_bound (const char *s1, const char *s2, int n)
 Calculate hamming distance between two sequences up to a specified length. More...
 
char * get_line (FILE *fp)
 Read a line of arbitrary length from a stream. More...
 
unsigned int get_input_line (char **string, unsigned int options)
 
void vrna_message_input_seq_simple (void)
 Print a line to stdout that asks for an input sequence. More...
 
void vrna_message_input_seq (const char *s)
 Print a line with a user defined string and a ruler to stdout. More...
 
void vrna_seq_toRNA (char *sequence)
 Convert an input sequence (possibly containing DNA alphabet characters) to RNA alphabet. More...
 
void vrna_seq_toupper (char *sequence)
 Convert an input sequence to uppercase. More...
 
int * vrna_get_iindx (unsigned int length)
 Get an index mapper array (iindx) for accessing the energy matrices, e.g. in partition function related functions. More...
 
int * vrna_get_indx (unsigned int length)
 Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions. More...
 
short * vrna_seq_encode (const char *sequence, vrna_md_t *md)
 Get a numerical representation of the nucleotide sequence.
 
short * vrna_seq_encode_simple (const char *sequence, vrna_md_t *md)
 Get a numerical representation of the nucleotide sequence (simple version)
 
int vrna_nucleotide_encode (char c, vrna_md_t *md)
 Encode a nucleotide character to numerical value. More...
 
char vrna_nucleotide_decode (int enc, vrna_md_t *md)
 Decode a numerical representation of a nucleotide back into nucleotide alphabet. More...
 
char * vrna_get_ptypes (const short *S, vrna_md_t *md)
 Get an array of the numerical encoding for each possible base pair (i,j) More...
 
void str_uppercase (char *sequence)
 Convert an input sequence to uppercase. More...
 
void str_DNA2RNA (char *sequence)
 Convert a DNA input sequence to RNA alphabet. More...
 
void print_tty_input_seq (void)
 Print a line to stdout that asks for an input sequence. More...
 
void print_tty_input_seq_str (const char *s)
 Print a line with a user defined string and a ruler to stdout. More...
 
void warn_user (const char message[])
 Print a warning message. More...
 
void nrerror (const char message[])
 Die with an error message. More...
 
void * space (unsigned size)
 Allocate space safely. More...
 
void * xrealloc (void *p, unsigned size)
 Reallocate space safely. More...
 
void init_rand (void)
 Make random number seeds. More...
 
double urn (void)
 get a random number from [0..1] More...
 
int int_urn (int from, int to)
 Generates a pseudo random integer in a specified range. More...
 
char * random_string (int l, const char symbols[])
 Create a random string using characters from a specified symbol set. More...
 
void filecopy (FILE *from, FILE *to)
 Inefficient cp More...
 
char * time_stamp (void)
 Get a timestamp. More...
 
int hamming (const char *s1, const char *s2)
 Calculate hamming distance between two sequences. More...
 
int hamming_bound (const char *s1, const char *s2, int n)
 Calculate hamming distance between two sequences up to a specified length. More...
 

Variables

unsigned short xsubi [3]
 Current 48 bit random number. More...
 

Detailed Description

Macro Definition Documentation

#define VRNA_INPUT_FASTA_HEADER   8U

Input/Output flag of get_input_line():
if used as input option this tells get_input_line() that the data to be read should comply with the FASTA format.

the function will return this flag if a fasta header was read

#define VRNA_INPUT_CONSTRAINT   32U

Input flag for get_input_line():
Tell get_input_line() that we assume to read a structure constraint.

#define VRNA_INPUT_NOSKIP_COMMENTS   128U

switch for get_input_line(): "do not skip comment lines"

#define VRNA_OPTION_MULTILINE   32U

Tell a function that an input is assumed to span several lines.

If used as input-option a function might also be returning this state telling that it has read data from multiple lines.

See also
vrna_extract_record_rest_structure(), vrna_read_fasta_record(), vrna_extract_record_rest_constraint()
#define FILENAME_MAX_LENGTH   80

Maximum length of filenames that are generated by our programs.

This definition should be used throughout the complete ViennaRNA package wherever a static array holding filenames of output files is declared.

#define FILENAME_ID_LENGTH   42

Maximum length of id taken from fasta header for filename generation.

this has to be smaller than FILENAME_MAX_LENGTH since in most cases, some suffix will be appended to the ID

Function Documentation

void* vrna_alloc ( unsigned  size)

Allocate space safely.

Parameters
sizeThe size of the memory to be allocated in bytes
Returns
A pointer to the allocated memory
void* vrna_realloc ( void *  p,
unsigned  size 
)

Reallocate space safely.

Parameters
pA pointer to the memory region to be reallocated
sizeThe size of the memory to be allocated in bytes
Returns
A pointer to the newly allocated memory
void vrna_message_error ( const char  message[])

Die with an error message.

See also
vrna_message_warning()
Parameters
messageThe error message to be printed before exiting with 'FAILURE'
void vrna_message_warning ( const char  message[])

Print a warning message.

Print a warning message to stderr

Parameters
messageThe warning message
double vrna_urn ( void  )

get a random number from [0..1]

See also
vrna_int_urn(), vrna_init_rand()
Note
Usually implemented by calling erand48().
Returns
A random number in range [0..1]
int vrna_int_urn ( int  from,
int  to 
)

Generates a pseudo random integer in a specified range.

See also
vrna_urn(), vrna_init_rand()
Parameters
fromThe first number in range
toThe last number in range
Returns
A pseudo random number in range [from, to]
char* vrna_time_stamp ( void  )

Get a timestamp.

Returns a string containing the current date in the format

Fri Mar 19 21:10:57 1993 
Returns
A string containing the timestamp
char* vrna_random_string ( int  l,
const char  symbols[] 
)

Create a random string using characters from a specified symbol set.

Parameters
lThe length of the sequence
symbolsThe symbol set
Returns
A random string of length 'l' containing characters from the symbolset
int vrna_hamming_distance ( const char *  s1,
const char *  s2 
)

Calculate hamming distance between two sequences.

Parameters
s1The first sequence
s2The second sequence
Returns
The hamming distance between s1 and s2
int vrna_hamming_distance_bound ( const char *  s1,
const char *  s2,
int  n 
)

Calculate hamming distance between two sequences up to a specified length.

This function is similar to vrna_hamming_distance() but instead of comparing both sequences up to their actual length only the first 'n' characters are taken into account

Parameters
s1The first sequence
s2The second sequence
Returns
The hamming distance between s1 and s2
char* get_line ( FILE *  fp)

Read a line of arbitrary length from a stream.

Returns a pointer to the resulting string. The necessary memory is allocated and should be released using free() when the string is no longer needed.

Parameters
fpA file pointer to the stream where the function should read from
Returns
A pointer to the resulting string
unsigned int get_input_line ( char **  string,
unsigned int  options 
)

Retrieve a line from 'stdin' savely while skipping comment characters and other features This function returns the type of input it has read if recognized. An option argument allows to switch between different reading modes.
Currently available options are:
#VRNA_INPUT_NOPRINT_COMMENTS, VRNA_INPUT_NOSKIP_COMMENTS, #VRNA_INPUT_NOELIM_WS_SUFFIX

pass a collection of options as one value like this:

get_input_line(string, option_1 | option_2 | option_n) 

If the function recognizes the type of input, it will report it in the return value. It also reports if a user defined 'quit' command (@-sign on 'stdin') was given. Possible return values are:
VRNA_INPUT_FASTA_HEADER, VRNA_INPUT_ERROR, VRNA_INPUT_MISC, VRNA_INPUT_QUIT

Parameters
stringA pointer to the character array that contains the line read
optionsA collection of options for switching the functions behavior
Returns
A flag with information about what has been read
void vrna_message_input_seq_simple ( void  )

Print a line to stdout that asks for an input sequence.

There will also be a ruler (scale line) printed that helps orientation of the sequence positions

void vrna_message_input_seq ( const char *  s)

Print a line with a user defined string and a ruler to stdout.

(usually this is used to ask for user input) There will also be a ruler (scale line) printed that helps orientation of the sequence positions

Parameters
sA user defined string that will be printed to stdout
void vrna_seq_toRNA ( char *  sequence)

Convert an input sequence (possibly containing DNA alphabet characters) to RNA alphabet.

This function substitudes T and t with U and u, respectively

Parameters
sequenceThe sequence to be converted
void vrna_seq_toupper ( char *  sequence)

Convert an input sequence to uppercase.

Parameters
sequenceThe sequence to be converted
int* vrna_get_iindx ( unsigned int  length)

Get an index mapper array (iindx) for accessing the energy matrices, e.g. in partition function related functions.

Access of a position "(i,j)" is then accomplished by using

(i,j) ~ iindx[i]-j 

This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout the ViennaRNA Package

Consult the implemented code to find out about the mapping formula ;)

See also
vrna_get_indx()
Parameters
lengthThe length of the RNA sequence
Returns
The mapper array
int* vrna_get_indx ( unsigned int  length)

Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions.

Access of a position "(i,j)" is then accomplished by using

(i,j) ~ indx[j]+i 

This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout the ViennaRNAPackage

Consult the implemented code to find out about the mapping formula ;)

See also
vrna_get_iindx()
Parameters
lengthThe length of the RNA sequence
Returns
The mapper array
int vrna_nucleotide_encode ( char  c,
vrna_md_t md 
)

Encode a nucleotide character to numerical value.

This function encodes a nucleotide character to its numerical representation as required by many functions in RNAlib.

See also
vrna_nucleotide_decode(), vrna_seq_encode()
Parameters
cThe nucleotide character to encode
mdThe model details that determine the kind of encoding
Returns
The encoded nucleotide
char vrna_nucleotide_decode ( int  enc,
vrna_md_t md 
)

Decode a numerical representation of a nucleotide back into nucleotide alphabet.

This function decodes a numerical representation of a nucleotide character back into nucleotide alphabet

See also
vrna_nucleotide_encode(), vrna_seq_encode()
Parameters
encThe encoded nucleotide
mdThe model details that determine the kind of decoding
Returns
The decoded nucleotide character
char* vrna_get_ptypes ( const short *  S,
vrna_md_t md 
)

Get an array of the numerical encoding for each possible base pair (i,j)

Note
This array is always indexed via jindx, in contrast to previously different indexing between mfe and pf variants!
See also
vrna_get_indx(), vrna_fold_compound
void str_uppercase ( char *  sequence)

Convert an input sequence to uppercase.

Deprecated:
Use vrna_seq_toupper() instead!
void str_DNA2RNA ( char *  sequence)

Convert a DNA input sequence to RNA alphabet.

Deprecated:
Use vrna_seq_toRNA() instead!
void print_tty_input_seq ( void  )

Print a line to stdout that asks for an input sequence.

There will also be a ruler (scale line) printed that helps orientation of the sequence positions

Deprecated:
Use vrna_message_input_seq_simple() instead!
void print_tty_input_seq_str ( const char *  s)

Print a line with a user defined string and a ruler to stdout.

(usually this is used to ask for user input) There will also be a ruler (scale line) printed that helps orientation of the sequence positions

Deprecated:
Use vrna_message_input_seq() instead!
void warn_user ( const char  message[])

Print a warning message.

Print a warning message to stderr

Deprecated:
Use vrna_message_warning() instead!
void nrerror ( const char  message[])

Die with an error message.

Deprecated:
Use vrna_message_error() instead!
void* space ( unsigned  size)

Allocate space safely.

Deprecated:
Use vrna_alloc() instead!
void* xrealloc ( void *  p,
unsigned  size 
)

Reallocate space safely.

Deprecated:
Use vrna_realloc() instead!
void init_rand ( void  )

Make random number seeds.

Deprecated:
Use vrna_init_rand() instead!
double urn ( void  )

get a random number from [0..1]

Deprecated:
Use vrna_urn() instead!
int int_urn ( int  from,
int  to 
)

Generates a pseudo random integer in a specified range.

Deprecated:
Use vrna_int_urn() instead!
char* random_string ( int  l,
const char  symbols[] 
)

Create a random string using characters from a specified symbol set.

Deprecated:
Use vrna_random_string() instead!
void filecopy ( FILE *  from,
FILE *  to 
)

Inefficient cp

Deprecated:
Use vrna_file_copy() instead!
char* time_stamp ( void  )

Get a timestamp.

Deprecated:
Use vrna_time_stamp() instead!
int hamming ( const char *  s1,
const char *  s2 
)

Calculate hamming distance between two sequences.

Deprecated:
Use vrna_hamming_distance() instead!
int hamming_bound ( const char *  s1,
const char *  s2,
int  n 
)

Calculate hamming distance between two sequences up to a specified length.

Deprecated:
Use vrna_hamming_distance_bound() instead!

Variable Documentation

unsigned short xsubi[3]

Current 48 bit random number.

This variable is used by vrna_urn(). These should be set to some random number seeds before the first call to vrna_urn().

See also
vrna_urn()