# The Fold Compound

This module provides interfaces that deal with the most basic data structure used in structure predicting and energy evaluating function of the RNAlib.

Throughout the entire RNAlib, the `vrna_fold_compound_t`, is used to group information and data that is required for structure prediction and energy evaluation. Here, you’ll find interface functions to create, modify, and delete `vrna_fold_compound_t` data structures.

  Defines

  VRNA_STATUS_MFE_PRE
    #include <ViennaRNA/fold_compound.h>

    Status message indicating that MFE computations are about to begin.

    See also

    vrna_fold_compound_t.stat_cb, vrna_recursion_status_f(), vrna_mfe(), vrna_fold(), vrna_circfold(), vrna_alifold(), vrna_circalifold(), vrna_cofold()

  VRNA_STATUS_MFE_POST
    #include <ViennaRNA/fold_compound.h>

    Status message indicating that MFE computations are finished.

    See also

    vrna_fold_compound_t.stat_cb, vrna_recursion_status_f(), vrna_mfe(), vrna_fold(), vrna_circfold(), vrna_alifold(), vrna_circalifold(), vrna_cofold()

  VRNA_STATUS_PF_PRE
    #include <ViennaRNA/fold_compound.h>

    Status message indicating that Partition function computations are about to begin.

    See also

    vrna_fold_compound_t.stat_cb, vrna_recursion_status_f(), vrna_pf()

  VRNA_STATUS_PF_POST
    #include <ViennaRNA/fold_compound.h>

    Status message indicating that Partition function computations are finished.

    See also

    vrna_fold_compound_t.stat_cb, vrna_recursion_status_f(), vrna_pf()

  VRNA_OPTION_DEFAULT
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify default settings/requirements.

  VRNA_OPTION_MFE
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.

    See also

    vrna_fold_compound(), vrna_fold_compound_comparative(), VRNA_OPTION_EVAL_ONLY

  VRNA_OPTION_PF
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.

    See also

    vrna_fold_compound(), vrna_fold_compound_comparative(), VRNA_OPTION_EVAL_ONLY

  VRNA_OPTION_HYBRID
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify requirement of dimer DP matrices.

  VRNA_OPTION_EVAL_ONLY
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify that neither MFE, nor PF DP matrices are required.

    Use this flag in conjuntion with VRNA_OPTION_MFE, and VRNA_OPTION_PF to save memory for a vrna_fold_compound_t obtained from vrna_fold_compound(), or vrna_fold_compound_comparative() in cases where only energy evaluation but no structure prediction is required.

    See also

    vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_eval_structure()

  VRNA_OPTION_WINDOW
    #include <ViennaRNA/fold_compound.h>

    Option flag to specify requirement of DP matrices for local folding approaches.

  VRNA_OPTION_F5
    #include <ViennaRNA/fold_compound.h>
  VRNA_OPTION_F3
    #include <ViennaRNA/fold_compound.h>
  VRNA_OPTION_WINDOW_F5
    #include <ViennaRNA/fold_compound.h>
  VRNA_OPTION_WINDOW_F3
    #include <ViennaRNA/fold_compound.h>

  Typedefs

  typedef struct vrna_fc_s vrna_fold_compound_t
    #include <ViennaRNA/fold_compound.h>

    Typename for the fold_compound data structure vrna_fc_s.

  typedef void (*vrna_auxdata_free_f)(void *data)
    #include <ViennaRNA/fold_compound.h>

    Callback to free memory allocated for auxiliary user-provided data.

    This type of user-implemented function usually deletes auxiliary data structures. The user must take care to free all the memory occupied by the data structure passed.

    Notes on Callback Functions:

      This callback is supposed to free memory occupied by an auxiliary data structure. It will be called when the vrna_fold_compound_t is erased from memory through a call to vrna_fold_compound_free() and will be passed the address of memory previously bound to the vrna_fold_compound_t via vrna_fold_compound_add_auxdata().

    See also

    vrna_fold_compound_add_auxdata(), vrna_fold_compound_free(), vrna_fold_compound_add_callback()

    Param data:

      The data that needs to be free’d

  typedef int (*vrna_auxdata_prepare_f)( vrna_fold_compound_t *fc, void *data, unsigned int event, void *event_data)
    #include <ViennaRNA/fold_compound.h>
  void() vrna_callback_free_auxdata (void *data)
    #include <ViennaRNA/fold_compound.h>

    Callback to free memory allocated for auxiliary user-provided data.

    Deprecated:

      Use vrna_auxdata_free_f(void *data) instead!

  typedef void (*vrna_recursion_status_f)(unsigned char status, void *data)
    #include <ViennaRNA/fold_compound.h>

    Callback to perform specific user-defined actions before, or after recursive computations.

    Notes on Callback Functions:

      This function will be called to notify a third-party implementation about the status of a currently ongoing recursion. The purpose of this callback mechanism is to provide users with a simple way to ensure pre- and post conditions for auxiliary mechanisms attached to our implementations.

    See also

    vrna_fold_compound_add_auxdata(), vrna_fold_compound_add_callback(), vrna_mfe(), vrna_pf(), VRNA_STATUS_MFE_PRE, VRNA_STATUS_MFE_POST, VRNA_STATUS_PF_PRE, VRNA_STATUS_PF_POST

    Param status:

      The status indicator

    Param data:

      The data structure that was assigned with vrna_fold_compound_add_auxdata()

  void() vrna_callback_recursion_status (unsigned char status, void *data)
    #include <ViennaRNA/fold_compound.h>

  Enums

  enum vrna_fc_type_e

    An enumerator that is used to specify the type of a vrna_fold_compound_t.

    Values:

    enumerator VRNA_FC_TYPE_SINGLE

      Type is suitable for single, and hybridizing sequences

    enumerator VRNA_FC_TYPE_COMPARATIVE

      Type is suitable for sequence alignments (consensus structure prediction)

  Functions

  vrna_fold_compound_t *vrna_fold_compound(const char *sequence, const vrna_md_t *md_p, unsigned int options)
    #include <ViennaRNA/fold_compound.h>

    Retrieve a vrna_fold_compound_t data structure for single sequences and hybridizing sequences.

    This function provides an easy interface to obtain a prefilled vrna_fold_compound_t by passing a single sequence, or two contatenated sequences as input. For the latter, sequences need to be seperated by an ‘&’ character like this:

        char *sequence = "GGGG&CCCC";

    The optional parameter `md_p` can be used to specify the model details for successive computations based on the content of the generated vrna_fold_compound_t. Passing NULL will instruct the function to use default model details. The third parameter `options` may be used to specify dynamic programming (DP) matrix requirements.

    Options

    - VRNA_OPTION_DEFAULT - Option flag to specify default settings/requirements.

    - VRNA_OPTION_MFE - Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.

    - VRNA_OPTION_PF - Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.

    - VRNA_OPTION_WINDOW - Option flag to specify requirement of DP matrices for local folding approaches.

    The above options may be OR-ed together.

    If you just need the folding compound serving as a container for your data, you can simply pass VRNA_OPTION_DEFAULT to the `option` parameter. This creates a vrna_fold_compound_t without DP matrices, thus saving memory. Subsequent calls of any structure prediction function will then take care of allocating the memory required for the DP matrices. If you only intend to evaluate structures instead of actually predicting them, you may use the VRNA_OPTION_EVAL_ONLY macro. This will seriously speedup the creation of the vrna_fold_compound_t.

    See also

    vrna_fold_compound_free(), vrna_fold_compound_comparative(), vrna_md_t

    Note

    The sequence string must be uppercase, and should contain only RNA (resp. DNA) alphabet depending on what energy parameter set is used

    Parameters:

      - sequence – A single sequence, or two concatenated sequences seperated by an ‘&’ character

      - md_p – An optional set of model details

      - options – The options for DP matrices memory allocation

    Returns:

      A prefilled vrna_fold_compound_t ready to be used for computations (may be `NULL` on error)

  vrna_fold_compound_t *vrna_fold_compound_comparative(const char **sequences, vrna_md_t *md_p, unsigned int options)
    #include <ViennaRNA/fold_compound.h>

    Retrieve a vrna_fold_compound_t data structure for sequence alignments.

    This function provides an easy interface to obtain a prefilled vrna_fold_compound_t by passing an alignment of sequences.

    The optional parameter `md_p` can be used to specify the model details for successive computations based on the content of the generated vrna_fold_compound_t. Passing NULL will instruct the function to use default model details. The third parameter `options` may be used to specify dynamic programming (DP) matrix requirements.

    Options

    - VRNA_OPTION_DEFAULT - Option flag to specify default settings/requirements.

    - VRNA_OPTION_MFE - Option flag to specify requirement of Minimum Free Energy (MFE) DP matrices and corresponding set of energy parameters.

    - VRNA_OPTION_PF - Option flag to specify requirement of Partition Function (PF) DP matrices and corresponding set of Boltzmann factors.

    - VRNA_OPTION_WINDOW - Option flag to specify requirement of DP matrices for local folding approaches.

    The above options may be OR-ed together.

    If you just need the folding compound serving as a container for your data, you can simply pass VRNA_OPTION_DEFAULT to the `option` parameter. This creates a vrna_fold_compound_t without DP matrices, thus saving memory. Subsequent calls of any structure prediction function will then take care of allocating the memory required for the DP matrices. If you only intend to evaluate structures instead of actually predicting them, you may use the VRNA_OPTION_EVAL_ONLY macro. This will seriously speedup the creation of the vrna_fold_compound_t.

    See also

    vrna_fold_compound_free(), vrna_fold_compound(), vrna_md_t, VRNA_OPTION_MFE, VRNA_OPTION_PF, VRNA_OPTION_EVAL_ONLY, read_clustal()

    Note

    The sequence strings must be uppercase, and should contain only RNA (resp. DNA) alphabet including gap characters depending on what energy parameter set is used.

    Parameters:

      - sequences – A sequence alignment including ‘gap’ characters

      - md_p – An optional set of model details

      - options – The options for DP matrices memory allocation

    Returns:

      A prefilled vrna_fold_compound_t ready to be used for computations (may be `NULL` on error)

  vrna_fold_compound_t *vrna_fold_compound_comparative2(const char **sequences, const char **names, const unsigned char *orientation, const unsigned long long *start, const unsigned long long *genome_size, vrna_md_t *md_p, unsigned int options)
    #include <ViennaRNA/fold_compound.h>
  vrna_fold_compound_t *vrna_fold_compound_TwoD(const char *sequence, const char *s1, const char *s2, vrna_md_t *md_p, unsigned int options)
    #include <ViennaRNA/fold_compound.h>
  int vrna_fold_compound_prepare( vrna_fold_compound_t *fc, unsigned int options)
    #include <ViennaRNA/fold_compound.h>
  void vrna_fold_compound_free( vrna_fold_compound_t *fc)
    #include <ViennaRNA/fold_compound.h>

    Free memory occupied by a vrna_fold_compound_t.

    See also

    vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_mx_mfe_free(), vrna_mx_pf_free()

    Parameters:

      - fc – The vrna_fold_compound_t that is to be erased from memory

  void vrna_fold_compound_add_auxdata( vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f)
    #include <ViennaRNA/fold_compound.h>

    Add auxiliary data to the vrna_fold_compound_t.

    This function allows one to bind arbitrary data to a vrna_fold_compound_t which may later on be used by one of the callback functions, e.g. vrna_recursion_status_f(). To allow for proper cleanup of the memory occupied by this auxiliary data, the user may also provide a pointer to a cleanup function that free’s the corresponding memory. This function will be called automatically when the vrna_fold_compound_t is free’d with vrna_fold_compound_free().

    See also

    vrna_auxdata_free_f()

    Note

    Before attaching the arbitrary data pointer, this function will call the vrna_auxdata_free_f() on any pre-existing data that is already attached.

    Parameters:

      - fc – The fold_compound the arbitrary data pointer should be associated with

      - data – A pointer to an arbitrary data structure

      - f – A pointer to function that free’s memory occupied by the arbitrary data (May be NULL)

  void vrna_fold_compound_add_callback( vrna_fold_compound_t *fc, vrna_recursion_status_f f)
    #include <ViennaRNA/fold_compound.h>

    Add a recursion status callback to the vrna_fold_compound_t.

    Binding a recursion status callback function to a vrna_fold_compound_t allows one to perform arbitrary operations just before, or after an actual recursive computations, e.g. MFE prediction, is performed by the RNAlib. The callback function will be provided with a pointer to its vrna_fold_compound_t, and a status message. Hence, it has complete access to all variables that incluence the recursive computations.

    See also

    vrna_recursion_status_f(), vrna_fold_compound_t, VRNA_STATUS_MFE_PRE, VRNA_STATUS_MFE_POST, VRNA_STATUS_PF_PRE, VRNA_STATUS_PF_POST

    Parameters:

      - fc – The fold_compound the callback function should be attached to

      - f – The pointer to the recursion status callback function

  struct vrna_fc_s
    #include <ViennaRNA/fold_compound.h>

    The most basic data structure required by many functions throughout the RNAlib.

    SWIG Wrapper Notes:

      This data structure is wrapped as class `fold_compound` with several related functions attached as methods.

      A new `fold_compound` can be obtained by calling one of its constructors:

      - `fold_compound(seq)` - Initialize with a single sequence, or two concatenated sequences separated by an ampersand character `&` (for cofolding)

      - `fold_compound(aln)` - Initialize with a sequence alignment aln stored as a list of sequences (with gap characters).

      The resulting object has a list of attached methods which in most cases directly correspond to functions that mainly operate on the corresponding `C` data structure:

      - `type()` - Get the type of the fold_compound (See vrna_fc_type_e)

      - `length()` - Get the length of the sequence(s) or alignment stored within the `fold_compound`.

      See, e.g. `RNA.fold_compound` in the Python API.

    See also

    vrna_fold_compound_t.type, vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_fold_compound_free(), VRNA_FC_TYPE_SINGLE, VRNA_FC_TYPE_COMPARATIVE

    Note

    Please read the documentation of this data structure carefully! Some attributes are only available for specific types this data structure can adopt.

    Warning

    Reading/Writing from/to attributes that are not within the scope of the current type usually result in undefined behavior!

    Common data fields

    const vrna_fc_type_e type

      The type of the vrna_fold_compound_t.

      Currently possible values are VRNA_FC_TYPE_SINGLE, and VRNA_FC_TYPE_COMPARATIVE

      Warning

      Do not edit this attribute, it will be automagically set by the corresponding get() methods for the vrna_fold_compound_t. The value specified in this attribute dictates the set of other attributes to use within this data structure.

    unsigned int length

      The length of the sequence (or sequence alignment)

    int cutpoint

      The position of the (cofold) cutpoint within the provided sequence. If there is no cutpoint, this field will be set to -1.

    unsigned int *strand_number

      The strand number a particular nucleotide is associated with.

    unsigned int *strand_order

      The strand order, i.e. permutation of current concatenated sequence.

    unsigned int *strand_order_uniq

      The strand order array where identical sequences have the same ID.

    unsigned int *strand_start

      The start position of a particular strand within the current concatenated sequence.

    unsigned int *strand_end

      The end (last) position of a particular strand within the current concatenated sequence.

    unsigned int strands

      Number of interacting strands.

    vrna_seq_t *nucleotides

      Set of nucleotide sequences.

    vrna_msa_t *alignment

      Set of alignments.

    vrna_hc_t *hc

      The hard constraints data structure used for structure prediction.

    vrna_mx_mfe_t *matrices

      The MFE DP matrices.

    vrna_mx_pf_t *exp_matrices

      The PF DP matrices

    vrna_param_t *params

      The precomputed free energy contributions for each type of loop.

    vrna_exp_param_t *exp_params

      The precomputed free energy contributions as Boltzmann factors

    int *iindx

      DP matrix accessor

    int *jindx

      DP matrix accessor

    User-defined data fields

    vrna_recursion_status_f stat_cb

      Recursion status callback (usually called just before, and after recursive computations in the library.

      See also

      vrna_recursion_status_f(), vrna_fold_compound_add_callback()

    void *auxdata

      A pointer to auxiliary, user-defined data.

      See also

      vrna_fold_compound_add_auxdata(), vrna_fold_compound_t.free_auxdata

    vrna_auxdata_free_f free_auxdata

      A callback to free auxiliary user data whenever the fold_compound itself is free’d.

      See also

      vrna_fold_compound_t.auxdata, vrna_auxdata_free_f()

    Secondary Structure Decomposition (grammar) related data fields

    vrna_sd_t *domains_struc

      Additional structured domains.

    vrna_ud_t *domains_up

      Additional unstructured domains.

    vrna_gr_aux_t *aux_grammar

      Additional decomposition grammar rules.

    Data fields available for single/hybrid structure prediction

    char *sequence

      The input sequence string.

      Warning

      Only available if

          type==VRNA_FC_TYPE_SINGLE

    short *sequence_encoding

      Numerical encoding of the input sequence.

      See also

      vrna_sequence_encode()

      Warning

      Only available if

          type==VRNA_FC_TYPE_SINGLE

    short *encoding5
    short *encoding3
    short *sequence_encoding2
    char *ptype

      Pair type array.

      Contains the numerical encoding of the pair type for each pair (i,j) used in MFE, Partition function and Evaluation computations.

      See also

      vrna_idx_col_wise(), vrna_ptypes()

      Note

      This array is always indexed via jindx, in contrast to previously different indexing between mfe and pf variants!

      Warning

      Only available if

          type==VRNA_FC_TYPE_SINGLE

    char *ptype_pf_compat

      ptype array indexed via iindx

      Deprecated:

        This attribute will vanish in the future! It’s meant for backward compatibility only!

      Warning

      Only available if

          type==VRNA_FC_TYPE_SINGLE

    vrna_sc_t *sc

      The soft constraints for usage in structure prediction and evaluation.

      Warning

      Only available if

          type==VRNA_FC_TYPE_SINGLE

    Data fields for consensus structure prediction

    char **sequences

      The aligned sequences.

      Note

      The end of the alignment is indicated by a NULL pointer in the second dimension

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    unsigned int n_seq

      The number of sequences in the alignment.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    char *cons_seq

      The consensus sequence of the aligned sequences.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    short *S_cons

      Numerical encoding of the consensus sequence.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    short **S

      Numerical encoding of the sequences in the alignment.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    short **S5

      S5[s][i] holds next base 5’ of i in sequence s.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    short **S3

      Sl[s][i] holds next base 3’ of i in sequence s.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    char **Ss
    unsigned int **a2s
    int *pscore

      Precomputed array of pair types expressed as pairing scores.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    int **pscore_local

      Precomputed array of pair types expressed as pairing scores.

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    short *pscore_pf_compat

      Precomputed array of pair types expressed as pairing scores indexed via iindx.

      Deprecated:

        This attribute will vanish in the future!

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    vrna_sc_t **scs

      A set of soft constraints (for each sequence in the alignment)

      Warning

      Only available if

          type==VRNA_FC_TYPE_COMPARATIVE

    int oldAliEn

    Additional data fields for Distance Class Partitioning

    These data fields are typically populated with meaningful data only if used in the context of Distance Class Partitioning

    unsigned int maxD1

      Maximum allowed base pair distance to first reference.

    unsigned int maxD2

      Maximum allowed base pair distance to second reference.

    short *reference_pt1

      A pairtable of the first reference structure.

    short *reference_pt2

      A pairtable of the second reference structure.

    unsigned int *referenceBPs1

      Matrix containing number of basepairs of reference structure1 in interval [i,j].

    unsigned int *referenceBPs2

      Matrix containing number of basepairs of reference structure2 in interval [i,j].

    unsigned int *bpdist

      Matrix containing base pair distance of reference structure 1 and 2 on interval [i,j].

    unsigned int *mm1

      Maximum matching matrix, reference struct 1 disallowed.

    unsigned int *mm2

      Maximum matching matrix, reference struct 2 disallowed.

    Additional data fields for local folding

    These data fields are typically populated with meaningful data only if used in the context of local folding

    int window_size

      window size for local folding sliding window approach

    char **ptype_local

      Pair type array (for local folding)

    vrna_zsc_dat_t zscore_data

      Data structure with settings for z-score computations.

    Public Members

    union vrna_fc_s