Soft Constraints — ViennaRNA Package

# Soft Constraints

Functions and data structures for secondary structure soft constraints.

## Introduction

Soft-constraints are used to change position specific contributions in the recursions by adding bonuses/penalties in form of pseudo free energies to certain loop configurations.

Note

For the sake of memory efficiency, we do not implement a loop context aware version of soft constraints. The static soft constraints as implemented only distinguish unpaired from paired nucleotides. This is usually sufficient for most use-case scenarios. However, similar to hard constraints, an abstract soft constraints implementation using a callback mechanism exists, that allows for any soft constraint that is compatible with the RNA folding grammar. Thus, loop contexts and even individual derivation rules can be addressed separately for maximum flexibility in soft-constraints application.

## Common API symbols

  Typedefs

  typedef struct vrna_sc_s vrna_sc_t

    Typename for the soft constraints data structure vrna_sc_s.

        #include <ViennaRNA/constraints/soft.h>

  Enums

  enum vrna_sc_type_e

    The type of a soft constraint.

        #include <ViennaRNA/constraints/soft.h>

    Values:

    enumerator VRNA_SC_DEFAULT

      Default Soft Constraints.

    enumerator VRNA_SC_WINDOW

      Soft Constraints suitable for local structure prediction using window approach.

      See also

      vrna_mfe_window(), vrna_mfe_window_zscore(), pfl_fold()

  Functions

  void vrna_sc_init(vrna_fold_compound_t *fc)

    Initialize an empty soft constraints data structure within a vrna_fold_compound_t.

        #include <ViennaRNA/constraints/soft.h>

    This function adds a proper soft constraints data structure to the vrna_fold_compound_t data structure. If soft constraints already exist within the fold compound, they are removed.

    SWIG Wrapper Notes:

      This function is attached as method `sc_init()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_init()` in the Python API .

    See also

    vrna_sc_set_bp(), vrna_sc_set_up(), vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), vrna_sc_remove(), vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_pre(), vrna_sc_add_post()

    Note

    Accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE and VRNA_FC_TYPE_COMPARATIVE

    Parameters:

      - fc – The vrna_fold_compound_t where an empty soft constraint feature is to be added to

  int vrna_sc_prepare(vrna_fold_compound_t *fc, unsigned int options)

    Prepare soft constraints.

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_update(vrna_fold_compound_t *fc, unsigned int i, unsigned int options)

    Update/prepare soft constraints for sliding-window computations.

        #include <ViennaRNA/constraints/soft.h>

  void vrna_sc_remove(vrna_fold_compound_t *fc)

    Remove soft constraints from vrna_fold_compound_t.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as method `sc_remove()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_remove()` in the Python API .

    Note

    Accepts vrna_fold_compound_t of type VRNA_FC_TYPE_SINGLE and VRNA_FC_TYPE_COMPARATIVE

    Parameters:

      - fc – The vrna_fold_compound_t possibly containing soft constraints

  void vrna_sc_free(vrna_sc_t *sc)

    Free memory occupied by a vrna_sc_t data structure.

        #include <ViennaRNA/constraints/soft.h>

    Parameters:

      - sc – The data structure to free from memory

  struct vrna_sc_bp_storage_t
    #include <ViennaRNA/constraints/soft.h>

    A base pair constraint.

    Public Members

    unsigned int interval_start

          #include <ViennaRNA/constraints/soft.h>

    unsigned int interval_end

          #include <ViennaRNA/constraints/soft.h>

    int e

          #include <ViennaRNA/constraints/soft.h>

  struct vrna_sc_s
    #include <ViennaRNA/constraints/soft.h>

    The soft constraints data structure.

    Common data fields

    const vrna_sc_type_e type

      Type of the soft constraints data structure.

          #include <ViennaRNA/constraints/soft.h>

    unsigned int n

      Length of the sequence this soft constraints data structure belongs to.

          #include <ViennaRNA/constraints/soft.h>

    unsigned char state

      Current state of the soft constraints data structure.

          #include <ViennaRNA/constraints/soft.h>

    int **energy_up

      Energy contribution for stretches of unpaired nucleotides.

          #include <ViennaRNA/constraints/soft.h>

    FLT_OR_DBL **exp_energy_up

      Boltzmann Factors of the energy contributions for unpaired sequence stretches.

          #include <ViennaRNA/constraints/soft.h>

    int *up_storage

      Storage container for energy contributions per unpaired nucleotide.

          #include <ViennaRNA/constraints/soft.h>

    vrna_sc_bp_storage_t **bp_storage

      Storage container for energy contributions per base pair.

          #include <ViennaRNA/constraints/soft.h>

    int *energy_stack

      Pseudo Energy contribution per base pair involved in a stack.

          #include <ViennaRNA/constraints/soft.h>

    FLT_OR_DBL *exp_energy_stack

      Boltzmann weighted pseudo energy contribution per nucleotide involved in a stack.

          #include <ViennaRNA/constraints/soft.h>

    Global structure prediction data fields

    int *energy_bp

      Energy contribution for base pairs.

          #include <ViennaRNA/constraints/soft.h>

    FLT_OR_DBL *exp_energy_bp

      Boltzmann Factors of the energy contribution for base pairs.

          #include <ViennaRNA/constraints/soft.h>

    Local structure prediction data fields

    int **energy_bp_local

      Energy contribution for base pairs (sliding window approach).

          #include <ViennaRNA/constraints/soft.h>

    FLT_OR_DBL **exp_energy_bp_local

      Boltzmann Factors of the energy contribution for base pairs (sliding window approach).

          #include <ViennaRNA/constraints/soft.h>

    User-defined data fields

    vrna_sc_f f

      A function pointer used for pseudo energy contribution in MFE calculations.

          #include <ViennaRNA/constraints/soft.h>

      See also

      vrna_sc_add_f()

    vrna_sc_bt_f bt

      A function pointer used to obtain backtraced base pairs in loop regions that were altered by soft constrained pseudo energy contributions.

          #include <ViennaRNA/constraints/soft.h>

      See also

      vrna_sc_add_bt()

    vrna_sc_exp_f exp_f

      A function pointer used for pseudo energy contribution boltzmann factors in PF calculations.

          #include <ViennaRNA/constraints/soft.h>

      See also

      vrna_sc_add_exp_f()

    void *data

      A pointer to the data object provided for for pseudo energy contribution functions of the generic soft constraints feature.

          #include <ViennaRNA/constraints/soft.h>

    vrna_auxdata_prepare_f prepare_data

          #include <ViennaRNA/constraints/soft.h>

    vrna_auxdata_free_f free_data

          #include <ViennaRNA/constraints/soft.h>

    Public Members

    union vrna_sc_s

          #include <ViennaRNA/constraints/soft.h>

## Constraints for Unpaired Positions

  Functions

  int vrna_sc_set_up(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options)

    Set soft constraints for unpaired nucleotides.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as method `sc_set_up()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_set_up()` in the Python API .

    See also

    vrna_sc_add_up(), vrna_sc_set_bp(), vrna_sc_add_bp()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - constraints – A vector of pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

  int vrna_sc_set_up_comparative(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options)

    Set soft constraints for unpaired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    Use this function to set soft constraints for unpaired nucleotides for each sequence in the multiple sequence alignment (MSA). The constraints are provided as 0-based array of 1-based array with the actual pseudo energies, where the first dimension corresponds to the number (0-based) of the respective sequence in the alignment. If no constraints are provided for a particular sequence \( s \) in the MSA, the corresponding entry must be set to NULL.

    See also

    vrna_sc_set_up_comparative_seq(), vrna_sc_add_up_comparative(), vrna_sc_set_bp_comparative(), vrna_sc_add_stack_comparative(), vrna_sc_set_stack_comparative(), vrna_sc_set_up()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Warning

    Pseudo energies for all sequences must be provided in sequence coordinates rather than alignment coordinates!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - constraints – A 0-based array of 1-based arrays with pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

  int vrna_sc_set_up_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, const FLT_OR_DBL *constraints, unsigned int options)

    Set soft constraints for unpaired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    This is a convenience wrapper for vrna_sc_set_up_comparative() where only one particular sequence `s` is provided with constraints.

    See also

    vrna_sc_set_up_comparative(), vrna_sc_add_up_comparative_seq(), vrna_sc_set_bp_comparative_seq(), vrna_sc_add_stack_comparative_seq(), vrna_sc_set_stack_comparative_seq(), vrna_sc_set_up()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Warning

    Pseudo energies for all sequences must be provided in sequence coordinates rather than alignment coordinates!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - s – The 0-based number of the sequence in the alignment the constraints are provided for

      - constraints – A 1-based arrays with pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

  int vrna_sc_add_up(vrna_fold_compound_t *fc, unsigned int i, FLT_OR_DBL energy, unsigned int options)

    Add soft constraints for unpaired nucleotides.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `sc_add_up()` to objects of type `fold_compound`. The method either takes arguments for a single nucleotide \(i \) with the corresponding energy value:

        fold_compound.sc_add_up(i, energy, options)

    or an entire vector that stores free energy contributions for each nucleotide \(i \) with \( 1 \leq i \leq n \):

        fold_compound.sc_add_bp(vector, options)

    In both variants, the optional argument `options` defaults to VRNA_OPTION_DEFAULT. See, e.g. `RNA.fold_compound.sc_add_up()` in the Python API .

    See also

    vrna_sc_set_up(), vrna_sc_add_bp(), vrna_sc_set_bp(), vrna_sc_add_up_comparative()

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - i – The nucleotide position the soft constraint is added for

      - energy – The free energy (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

  int vrna_sc_add_up_comparative(vrna_fold_compound_t *fc, unsigned int *is, const FLT_OR_DBL *energies, unsigned int options)

    Add soft constraints for unpaired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    Use this function to add soft constraints for unpaired nucleotides for each sequence in the multiple sequence alignment (MSA). The constraints are provided as 0-based array of pseudo energies, one for each sequence in the MSA. If no constraints are provided for a particular sequence, the corrsponding `is` value must be 0.

    See also

    vrna_sc_set_up_comparative_seq(), vrna_sc_add_up_comparative(), vrna_sc_set_bp_comparative(), vrna_sc_add_stack_comparative(), vrna_sc_set_stack_comparative(), vrna_sc_add_up()

    Warning

    Pseudo energies for all sequences must be provided in sequence coordinates rather than alignment coordinates!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - is – A 0-based array of nucleotide positions the soft constraint is added for

      - energies – A 0-based array of free energies (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

  int vrna_sc_add_up_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, unsigned int i, const FLT_OR_DBL energy, unsigned int options)

    Add soft constraints for unpaired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    This is a convenience wrapper for vrna_sc_add_up_comparative() where only one particular sequence `s` is provided with constraints.

    See also

    vrna_sc_set_up_comparative_seq(), vrna_sc_add_up_comparative(), vrna_sc_set_bp_comparative(), vrna_sc_add_stack_comparative(), vrna_sc_set_stack_comparative(), vrna_sc_add_up()

    Warning

    Pseudo energies for all sequences must be provided in sequence coordinates rather than alignment coordinates!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - s – The 0-based number of the sequence in the alignment the constraints are provided for

      - i – The 1-based nucleotide position the soft constraint is added for

      - energy – The free energies (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

## Constraints for Base Pairs

  Functions

  int vrna_sc_set_bp(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options)

    Set soft constraints for paired nucleotides.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as method `sc_set_bp()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_set_bp()` in the Python API .

    See also

    vrna_sc_add_bp(), vrna_sc_set_up(), vrna_sc_add_up()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - constraints – A two-dimensional array of pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

  int vrna_sc_set_bp_comparative(vrna_fold_compound_t *fc, const FLT_OR_DBL ***constraints, unsigned int options)

    Set soft constraints for paired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    Similar to vrna_sc_set_bp() this function allows to set soft constraints \( e_{i,j}^\mathrm{BP} \) for all base pairs \( (i, j) \) at once using a 1-based upper-triangular matrix \( E_\mathrm{BP} \). Since this function is supposed to be used for comparative structure predictions over a multiple sequence alignment (MSA), a 0-based array of matrices must be supplied as parameter `constraints`. If no constraints are to be used for sequence \( s \) in the MSA, the corresponding entry may be set to NULL.

    See also

    vrna_sc_set_bp_comparative_seq(), vrna_sc_add_bp_comparative(), vrna_sc_set_up_comparative(), vrna_sc_add_up_comparative(), vrna_sc_set_stack_comparative(), vrna_sc_add_stack_comparative(), vrna_sc_set_bp()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Warning

    Currently, base pair constraints must be provided in alignment coordinates rather than sequence coordinates! This may change in the future!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - constraints – A 0-based array of 1-based two-dimensional arrays with pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

  int vrna_sc_set_bp_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, const FLT_OR_DBL **constraints, unsigned int options)

    Set soft constraints for paired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    This is a convenience wrapper for vrna_sc_set_bp_comparative() where only one particular sequence `s` is provided with constraints.

    See also

    vrna_sc_set_bp_comparative(), vrna_sc_add_bp_comparative(), vrna_sc_set_up_comparative_seq(), vrna_sc_add_up_comparative_seq(), vrna_sc_set_stack_comparative_seq(), vrna_sc_add_stack_comparative_seq(), vrna_sc_set_bp()

    Note

    This function replaces any pre-exisitng soft constraints with the ones supplied in `constraints`.

    Warning

    This function not only re-sets the constraints for sequence `s` in the MSA but will also remove all constraints for all other sequences!

    Warning

    Currently, base pair constraints must be provided in alignment coordinates rather than sequence coordinates! This may change in the future!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - s – The 0-based number of the sequence in the alignment the constraints are provided for

      - constraints – A 1-based two-dimensional array of pseudo free energies in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

  int vrna_sc_add_bp(vrna_fold_compound_t *fc, unsigned int i, unsigned int j, FLT_OR_DBL energy, unsigned int options)

    Add soft constraints for paired nucleotides.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as an overloaded method `sc_add_bp()` to objects of type `fold_compound`. The method either takes arguments for a single base pair (i,j) with the corresponding energy value:

        fold_compound.sc_add_bp(i, j, energy, options)

    or an entire 2-dimensional matrix with dimensions n x n that stores free energy contributions for any base pair (i,j) with \( 1 \leq i < j \leq n \):

        fold_compound.sc_add_bp(matrix, options)

    In both variants, the optional argument `options` defaults to VRNA_OPTION_DEFAULT. See, e.g. `RNA.fold_compound.sc_add_bp()` in the Python API .

    See also

    vrna_sc_set_bp(), vrna_sc_set_up(), vrna_sc_add_up()

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - i – The 5’ position of the base pair the soft constraint is added for

      - j – The 3’ position of the base pair the soft constraint is added for

      - energy – The free energy (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      Non-zero on successful application of the constraint, 0 otherwise.

  int vrna_sc_add_bp_comparative(vrna_fold_compound_t *fc, unsigned int *is, unsigned int *js, const FLT_OR_DBL *energies, unsigned int options)

    Add soft constraints for paired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    Similar to vrna_sc_add_bp(), this function allows to add soft constraints \( e_{i,j}^\mathrm{BP} \) for all base pairs \( (i, j) \) in the multiple sequence alignment (MSA). The actual pairing partners \( i \) and \( j \) for each sequence in the MSA are provided in the form of 0-based arrays as parameters `is` and `js`. The corresponding energy contributions are provided as 0-based array in parameter `energies`. If no constraint is provided for sequence \( s \) in the MSA, the corresponding `is` value must be set to 0.

    See also

    vrna_sc_add_bp_comparative_seq(), vrna_sc_set_bp_comparative(), vrna_sc_set_up_comparative(), vrna_sc_add_up_comparative(), vrna_sc_set_stack_comparative(), vrna_sc_add_stack_comparative(), vrna_sc_add_bp()

    Note

    Consecutive calls of this function with the same `is` and `js` accumulate to corresponding `energies` values, i.e. energies are added up onto each other.

    Warning

    Currently, base pair constraints must be provided in alignment coordinates rather than sequence coordinates! This may change in the future!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - is – A 0-based array of 5’ position of the base pairs the soft constraint is added for

      - js – A 0-based array of 3’ position of the base pairs the soft constraint is added for

      - energies – A 0-based array of free energies (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

  int vrna_sc_add_bp_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, unsigned int i, unsigned int j, FLT_OR_DBL energy, unsigned int options)

    Add soft constraints for paired nucleotides in comparative structure predictions.

        #include <ViennaRNA/constraints/soft.h>

    This is a convenience wrapper for vrna_sc_add_bp_comparative() where only one particular sequence `s` is provided with constraints.

    See also

    vrna_sc_add_bp_comparative(), vrna_sc_set_bp_comparative_seq(), vrna_sc_set_up_comparative_seq(), vrna_sc_add_up_comparative_seq(), vrna_sc_set_stack_comparative_seq(), vrna_sc_add_stack_comparative_seq(), vrna_sc_add_bp()

    Note

    Consecutive calls of this function with the same `i` and `j` accumulate to corresponding `energies` values, i.e. energies are added up onto each other.

    Warning

    Currently, base pair constraints must be provided in alignment coordinates rather than sequence coordinates! This may change in the future!

    Parameters:

      - fc – The vrna_fold_compound_t the soft constraints are associated with

      - s – The 0-based number of the sequence in the alignment the constraints are provided for

      - i – 5’ position of the base pairs the soft constraint is added for

      - j – 3’ position of the base pairs the soft constraint is added for

      - energy – Free energy (soft-constraint) in \( kcal / mol \)

      - options – The options flag indicating how/where to store the soft constraints

    Returns:

      The number of sequences in the MSA constraints have been applied to

## Constraints for Stacked Base Pairs

  Functions

  int vrna_sc_set_stack(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_stack_comparative(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_stack_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, const FLT_OR_DBL *constraints, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_stack(vrna_fold_compound_t *fc, unsigned int i, FLT_OR_DBL energy, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_stack_comparative(vrna_fold_compound_t *fc, unsigned int *is, const FLT_OR_DBL *energies, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_stack_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, unsigned int i, FLT_OR_DBL energy, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

## Generic implementation

  Typedefs

  typedef int (*vrna_sc_f)(int i, int j, int k, int l, unsigned char d, void *data)

    Callback to retrieve pseudo energy contribution for soft constraint feature.

        #include <ViennaRNA/constraints/soft.h>

    This is the prototype for callback functions used by the folding recursions to evaluate generic soft constraints. The first four parameters passed indicate the delimiting nucleotide positions of the decomposition, and the parameter `denotes` the decomposition step. The last parameter `data` is the auxiliary data structure associated to the hard constraints via vrna_sc_add_data(), or NULL if no auxiliary data was added.

    Notes on Callback Functions:

      This callback enables one to add (pseudo-)energy contributions to individual decompositions of the secondary structure.

    See also

    VRNA_DECOMP_PAIR_HP, VRNA_DECOMP_PAIR_IL, VRNA_DECOMP_PAIR_ML, VRNA_DECOMP_ML_ML_ML, VRNA_DECOMP_ML_STEM, VRNA_DECOMP_ML_ML, VRNA_DECOMP_ML_UP, VRNA_DECOMP_ML_ML_STEM, VRNA_DECOMP_ML_COAXIAL, VRNA_DECOMP_EXT_EXT, VRNA_DECOMP_EXT_UP, VRNA_DECOMP_EXT_STEM, VRNA_DECOMP_EXT_EXT_EXT, VRNA_DECOMP_EXT_STEM_EXT, VRNA_DECOMP_EXT_EXT_STEM, VRNA_DECOMP_EXT_EXT_STEM1, vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_bt(), vrna_sc_add_data()

    Param i:

      Left (5’) delimiter position of substructure

    Param j:

      Right (3’) delimiter position of substructure

    Param k:

      Left delimiter of decomposition

    Param l:

      Right delimiter of decomposition

    Param d:

      Decomposition step indicator

    Param data:

      Auxiliary data

    Return:

      Pseudo energy contribution in deka-kalories per mol

  typedef int (*vrna_sc_direct_f)(vrna_fold_compound_t *fc, int i, int j, int k, int l, void *data)

        #include <ViennaRNA/constraints/soft.h>

  typedef FLT_OR_DBL (*vrna_sc_exp_f)(int i, int j, int k, int l, unsigned char d, void *data)

    Callback to retrieve pseudo energy contribution as Boltzmann Factors for soft constraint feature.

        #include <ViennaRNA/constraints/soft.h>

    This is the prototype for callback functions used by the partition function recursions to evaluate generic soft constraints. The first four parameters passed indicate the delimiting nucleotide positions of the decomposition, and the parameter `denotes` the decomposition step. The last parameter `data` is the auxiliary data structure associated to the hard constraints via vrna_sc_add_data(), or NULL if no auxiliary data was added.

    Notes on Callback Functions:

      This callback enables one to add (pseudo-)energy contributions to individual decompositions of the secondary structure (Partition function variant, i.e. contributions must be returned as Boltzmann factors).

    See also

    VRNA_DECOMP_PAIR_HP, VRNA_DECOMP_PAIR_IL, VRNA_DECOMP_PAIR_ML, VRNA_DECOMP_ML_ML_ML, VRNA_DECOMP_ML_STEM, VRNA_DECOMP_ML_ML, VRNA_DECOMP_ML_UP, VRNA_DECOMP_ML_ML_STEM, VRNA_DECOMP_ML_COAXIAL, VRNA_DECOMP_EXT_EXT, VRNA_DECOMP_EXT_UP, VRNA_DECOMP_EXT_STEM, VRNA_DECOMP_EXT_EXT_EXT, VRNA_DECOMP_EXT_STEM_EXT, VRNA_DECOMP_EXT_EXT_STEM, VRNA_DECOMP_EXT_EXT_STEM1, vrna_sc_add_exp_f(), vrna_sc_add_f(), vrna_sc_add_bt(), vrna_sc_add_data()

    Param i:

      Left (5’) delimiter position of substructure

    Param j:

      Right (3’) delimiter position of substructure

    Param k:

      Left delimiter of decomposition

    Param l:

      Right delimiter of decomposition

    Param d:

      Decomposition step indicator

    Param data:

      Auxiliary data

    Return:

      Pseudo energy contribution in deka-kalories per mol

  typedef FLT_OR_DBL (*vrna_sc_exp_direct_f)(vrna_fold_compound_t *fc, int i, int j, int k, int l, void *data)

        #include <ViennaRNA/constraints/soft.h>

  typedef vrna_basepair_t *(*vrna_sc_bt_f)(int i, int j, int k, int l, unsigned char d, void *data)

    Callback to retrieve auxiliary base pairs for soft constraint feature.

        #include <ViennaRNA/constraints/soft.h>

    Notes on Callback Functions:

      This callback enables one to add auxiliary base pairs in the backtracking steps of hairpin- and internal loops.

    See also

    VRNA_DECOMP_PAIR_HP, VRNA_DECOMP_PAIR_IL, VRNA_DECOMP_PAIR_ML, VRNA_DECOMP_ML_ML_ML, VRNA_DECOMP_ML_STEM, VRNA_DECOMP_ML_ML, VRNA_DECOMP_ML_UP, VRNA_DECOMP_ML_ML_STEM, VRNA_DECOMP_ML_COAXIAL, VRNA_DECOMP_EXT_EXT, VRNA_DECOMP_EXT_UP, VRNA_DECOMP_EXT_STEM, VRNA_DECOMP_EXT_EXT_EXT, VRNA_DECOMP_EXT_STEM_EXT, VRNA_DECOMP_EXT_EXT_STEM, VRNA_DECOMP_EXT_EXT_STEM1, vrna_sc_add_bt(), vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_data()

    Param i:

      Left (5’) delimiter position of substructure

    Param j:

      Right (3’) delimiter position of substructure

    Param k:

      Left delimiter of decomposition

    Param l:

      Right delimiter of decomposition

    Param d:

      Decomposition step indicator

    Param data:

      Auxiliary data

    Return:

      List of additional base pairs

  Functions

  DEPRECATED (typedef int(vrna_callback_sc_energy)(int i, int j, int k, int l, unsigned char d, void *data), "Use vrna_sc_f instead!")

        #include <ViennaRNA/constraints/soft.h>

  DEPRECATED (typedef FLT_OR_DBL(vrna_callback_sc_exp_energy)(int i, int j, int k, int l, unsigned char d, void *data), "Use vrna_sc_exp_f instead!")

        #include <ViennaRNA/constraints/soft.h>

  DEPRECATED (typedef vrna_basepair_t *(vrna_callback_sc_backtrack)(int i, int j, int k, int l, unsigned char d, void *data), "Use vrna_sc_bt_f instead")

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f free_data)

    Add an auxiliary data structure for the generic soft constraints callback function.

        #include <ViennaRNA/constraints/soft.h>

    SWIG Wrapper Notes:

      This function is attached as method `sc_add_data()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_add_data()` in the Python API .

    See also

    vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_bt()

    Parameters:

      - fc – The fold compound the generic soft constraint function should be bound to

      - data – A pointer to the data structure that holds required data for function ‘f’

      - free_data – A pointer to a function that free’s the memory occupied by `data` (Maybe NULL)

    Returns:

      Non-zero on successful binding the data (and free-function), 0 otherwise

  int vrna_sc_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_prepare_f prepare_cb, vrna_auxdata_free_f free_cb)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_data_comparative(vrna_fold_compound_t *fc, void **data, vrna_auxdata_free_f *free_data, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_data_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, void *data, vrna_auxdata_free_f free_data, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_auxdata_comparative(vrna_fold_compound_t *fc, void **data, vrna_auxdata_prepare_f *prepare_cbs, vrna_auxdata_free_f *free_data, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_auxdata_comparative_seq(vrna_fold_compound_t *fc, unsigned int s, void *data, vrna_auxdata_prepare_f prepare_cb, vrna_auxdata_free_f free_data, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_f(vrna_fold_compound_t *fc, vrna_sc_f f)

    Bind a function pointer for generic soft constraint feature (MFE version).

        #include <ViennaRNA/constraints/soft.h>

    This function allows one to easily bind a function pointer and corresponding data structure to the soft constraint part vrna_sc_t of the vrna_fold_compound_t. The function for evaluating the generic soft constraint feature has to return a pseudo free energy \( \hat{E} \) in \( dacal/mol \), where \( 1 dacal/mol = 10 cal/mol \).

    SWIG Wrapper Notes:

      This function is attached as method `sc_add_f()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_add_f()` in the Python API .

    See also

    vrna_sc_add_data(), vrna_sc_add_bt(), vrna_sc_add_exp_f()

    Parameters:

      - fc – The fold compound the generic soft constraint function should be bound to

      - f – A pointer to the function that evaluates the generic soft constraint feature

    Returns:

      Non-zero on successful binding the callback function, 0 otherwise

  size_t vrna_sc_multi_cb_add(vrna_fold_compound_t *fc, vrna_sc_direct_f cb, vrna_sc_exp_direct_f cb_exp, void *data, vrna_auxdata_prepare_f prepare_cb, vrna_auxdata_free_f free_cb, unsigned int decomp_type)

        #include <ViennaRNA/constraints/soft.h>

  size_t vrna_sc_multi_cb_add_comparative(vrna_fold_compound_t *fc, vrna_sc_direct_f *cbs, vrna_sc_exp_direct_f *cbs_exp, void **datas, vrna_auxdata_prepare_f *prepare_cbs, vrna_auxdata_free_f *free_cbs, unsigned int *ds, unsigned int multi_params)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_set_f_comparative(vrna_fold_compound_t *fc, vrna_sc_f *f, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>

  int vrna_sc_add_bt(vrna_fold_compound_t *fc, vrna_sc_bt_f f)

    Bind a backtracking function pointer for generic soft constraint feature.

        #include <ViennaRNA/constraints/soft.h>

    This function allows one to easily bind a function pointer to the soft constraint part vrna_sc_t of the vrna_fold_compound_t. The provided function should be used for backtracking purposes in loop regions that were altered via the generic soft constraint feature. It has to return an array of vrna_basepair_t data structures, were the last element in the list is indicated by a value of -1 in it’s i position.

    SWIG Wrapper Notes:

      This function is attached as method `sc_add_bt()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_add_bt()` in the Python API .

    See also

    vrna_sc_add_data(), vrna_sc_add_f(), vrna_sc_add_exp_f()

    Parameters:

      - fc – The fold compound the generic soft constraint function should be bound to

      - f – A pointer to the function that returns additional base pairs

    Returns:

      Non-zero on successful binding the callback function, 0 otherwise

  int vrna_sc_add_exp_f(vrna_fold_compound_t *fc, vrna_sc_exp_f exp_f)

    Bind a function pointer for generic soft constraint feature (PF version).

        #include <ViennaRNA/constraints/soft.h>

    This function allows one to easily bind a function pointer and corresponding data structure to the soft constraint part vrna_sc_t of the vrna_fold_compound_t. The function for evaluating the generic soft constraint feature has to return a pseudo free energy \( \hat{E} \) as Boltzmann factor, i.e. \( exp(- \hat{E} / kT) \). The required unit for \( E \) is \( cal/mol \).

    SWIG Wrapper Notes:

      This function is attached as method `sc_add_exp_f()` to objects of type `fold_compound`. See, e.g. `RNA.fold_compound.sc_add_exp_f()` in the Python API .

    See also

    vrna_sc_add_bt(), vrna_sc_add_f(), vrna_sc_add_data()

    Parameters:

      - fc – The fold compound the generic soft constraint function should be bound to

      - exp_f – A pointer to the function that evaluates the generic soft constraint feature

    Returns:

      Non-zero on successful binding the callback function, 0 otherwise

  int vrna_sc_set_exp_f_comparative(vrna_fold_compound_t *fc, vrna_sc_exp_f *exp_f, unsigned int options)

        #include <ViennaRNA/constraints/soft.h>