diff --git a/gen/Project.toml b/gen/Project.toml index 6014c12..c199ca9 100644 --- a/gen/Project.toml +++ b/gen/Project.toml @@ -2,5 +2,5 @@ Clang = "40e3b903-d033-50b4-a0cc-940c62c95e31" [compat] -Clang = "0.17.1" +Clang = "0.18.1" julia = "1.7" diff --git a/gen/README.md b/gen/README.md index bddbc0d..d1bffc7 100644 --- a/gen/README.md +++ b/gen/README.md @@ -1,4 +1,6 @@ -# How to generate the wrappers +# ViennaRNA libRNA wrapper generator + +## How to generate the wrappers 1. `cd` to this directory 2. run `julia --project generator.jl` @@ -7,3 +9,13 @@ 1. `cd` to this directory 2. run `julia --project` and then in the Julia REPL, run `pkg> up` + +## Notes on patches to headers + +Some headers of ViennaRNA have to be patched to be able to be parsed +by Clang.jl. These patches can be found are under the directory +`patches-for-headers/`. The patches are applied to a temporary copy +of the header files that is deleted after parsing by the +`generator.jl` script that generates the `../lib/LibRNA.jl` file. +This only needs to be done once on a developer's machine when the +header files change. diff --git a/gen/generator.jl b/gen/generator.jl index 29a16ec..7e343b1 100755 --- a/gen/generator.jl +++ b/gen/generator.jl @@ -5,6 +5,18 @@ import Pkg cd(@__DIR__) Pkg.activate(".") +function find_files_matching_regex(root_dir::AbstractString, regex::Regex) + matching_files = String[] + for (root, dirs, files) in walkdir(root_dir) + for file in files + if occursin(regex, file) + push!(matching_files, joinpath(root, file)) + end + end + end + return matching_files +end + # Stack environment from parent dir on top of env from this dir. This # is so we can import ViennaRNA_jll and always have the same version # as the parent dir. @@ -37,8 +49,19 @@ open("./prologue.jl", "w") do io println(io, "#### end prologue.jl") end -include_dir = normpath(ViennaRNA_jll.artifact_dir, "include") +#include_dir = normpath(ViennaRNA_jll.artifact_dir, "include") +#viennarna_dir = joinpath(include_dir, "ViennaRNA") +tmpdir = mktempdir() +run(`cp -r $(normpath(ViennaRNA_jll.artifact_dir, "include")) $tmpdir/`) +include_dir = joinpath(tmpdir, "include") viennarna_dir = joinpath(include_dir, "ViennaRNA") +patches_dir = abspath(joinpath("patches-for-headers")) +patch_files = filter(f -> endswith(f, ".patch"), readdir(patches_dir; join=true)) +cd(include_dir) do + for patch in patch_files + run(pipeline(`patch -p2`, stdin=patch)) #joinpath(patches_dir, "soft_special_missing_includes.patch"))) + end +end options = load_options(joinpath(@__DIR__, "generator.toml")) print("options =\n ") @@ -48,6 +71,8 @@ args = get_default_args() append!(args, [ "-I$include_dir", "-DVRNA_DISABLE_C11_FEATURES", +# "-DVRNA_DISABLE_BACKWARD_COMPATIBILITY", +# "-DMAXALPHA=20", ]) accept_headers = [ @@ -68,10 +93,17 @@ accept_headers = [ "subopt_zuker.h", "treedist.h", "utils/basic.h", + "constraints/basic.h", + "constraints/hard.h", + "constraints/ligand.h", + "constraints/SHAPE.h", + "constraints/soft.h", + "constraints/soft_special.h", ] headers = [joinpath(viennarna_dir, header) for header in accept_headers] # there is also an experimental `detect_headers` function for auto-detecting top-level headers in the directory -# headers = detect_headers(clang_dir, args) +#headers = detect_headers(viennarna_dir, args) +#headers = find_files_matching_regex(viennarna_dir, r".*\.h") # create context ctx = create_context(headers, args, options) diff --git a/gen/patches-for-headers/soft_special_missing_includes.patch b/gen/patches-for-headers/soft_special_missing_includes.patch new file mode 100644 index 0000000..5d146ee --- /dev/null +++ b/gen/patches-for-headers/soft_special_missing_includes.patch @@ -0,0 +1,14 @@ +diff --git a/src/ViennaRNA/constraints/soft_special.h b/src/ViennaRNA/constraints/soft_special.h +index 1902c930..654bc85e 100644 +--- a/src/ViennaRNA/constraints/soft_special.h ++++ b/src/ViennaRNA/constraints/soft_special.h +@@ -1,6 +1,9 @@ + #ifndef VIENNA_RNA_PACKAGE_CONSTRAINTS_SOFT_SPECIAL_H + #define VIENNA_RNA_PACKAGE_CONSTRAINTS_SOFT_SPECIAL_H + ++#include "ViennaRNA/fold_compound.h" ++#include "ViennaRNA/model.h" ++ + /** + * @file constraints/soft_special.h + * @ingroup soft_constraints, modified_bases diff --git a/lib/LibRNA.jl b/lib/LibRNA.jl index a5e7958..5f3e936 100644 --- a/lib/LibRNA.jl +++ b/lib/LibRNA.jl @@ -9,7 +9,7 @@ using CEnum # this file was autogenerated by gen/generator.jl # package versions used to generate this file -const VERSION_GEN_Clang = v"0.17.6" +const VERSION_GEN_Clang = v"0.18.1" const VERSION_GEN_ViennaRNA_jll = v"2.6.4+0" #### end prologue.jl @@ -2959,4244 +2959,4136 @@ function vrna_mx_pf_free(fc) end """ - vrna_hc_up_s - - @brief A single hard constraint for a single nucleotide - - @ingroup hard_constraints -""" -struct vrna_hc_up_s - position::Cint - strand::Cint - options::Cuchar -end - -""" - @brief Typename for the single nucleotide hard constraint data structure #vrna_hc_up_s - @ingroup hard_constraints -""" -const vrna_hc_up_t = vrna_hc_up_s - -""" - vrna_constraints_add(fc, constraint, options) - - @brief Add constraints to a #vrna_fold_compound_t data structure - - Use this function to add/update the hard/soft constraints - The function allows for passing a string 'constraint' that can either be a - filename that points to a constraints definition file or it may be a - pseudo dot-bracket notation indicating hard constraints. For the latter, the - user has to pass the #VRNA_CONSTRAINT_DB option. Also, the - user has to specify, which characters are allowed to be interpreted as - constraints by passing the corresponding options via the third parameter. - - @ingroup hard_constraints - - The following is an example for adding hard constraints given in - pseudo dot-bracket notation. Here, @p fc is the #vrna_fold_compound_t object, - @p structure is a char array with the hard constraint in dot-bracket notation, - and @p enforceConstraints is a flag indicating whether or not constraints for - base pairs should be enforced instead of just doing a removal of base pair that - conflict with the constraint. - - @snippet RNAfold.c Adding hard constraints from pseudo dot-bracket - - In constrat to the above, constraints may also be read from file: - - @snippet RNAfold.c Adding hard constraints from file + vrna_gr_set_aux_f(fc, cb) - @see vrna_hc_add_from_db(), vrna_hc_add_up(), vrna_hc_add_up_batch() - vrna_hc_add_bp_unspecific(), vrna_hc_add_bp(), - vrna_hc_init(), vrna_sc_set_up(), vrna_sc_set_bp(), - vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), - vrna_hc_free(), vrna_sc_free(), - #VRNA_CONSTRAINT_DB, #VRNA_CONSTRAINT_DB_DEFAULT, #VRNA_CONSTRAINT_DB_PIPE, - #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, - #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTRAMOL, - #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_GQUAD - @param fc The fold compound - @param constraint A string with either the filename of the constraint definitions - or a pseudo dot-bracket notation of the hard constraint. May be NULL. - @param options The option flags ### Prototype ```c -void vrna_constraints_add(vrna_fold_compound_t *fc, const char *constraint, unsigned int options); +int vrna_gr_set_aux_f(vrna_fold_compound_t *fc, vrna_grammar_rule_f cb); ``` """ -function vrna_constraints_add(fc, constraint, options) - ccall((:vrna_constraints_add, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cuint), fc, constraint, options) +function vrna_gr_set_aux_f(fc, cb) + ccall((:vrna_gr_set_aux_f, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f), fc, cb) end -# DEPRECATED -const vrna_callback_hc_evaluate = Cvoid - """ - vrna_message_constraint_options(option) - - @brief Print a help message for pseudo dot-bracket structure constraint characters to stdout. - (constraint support is specified by option parameter) - - Currently available options are:\\n - #VRNA_CONSTRAINT_DB_PIPE (paired with another base)\\n - #VRNA_CONSTRAINT_DB_DOT (no constraint at all)\\n - #VRNA_CONSTRAINT_DB_X (base must not pair)\\n - #VRNA_CONSTRAINT_DB_ANG_BRACK (paired downstream/upstream)\\n - #VRNA_CONSTRAINT_DB_RND_BRACK (base i pairs base j)\\n - - pass a collection of options as one value like this: - @verbatim vrna_message_constraints(option_1 | option_2 | option_n) @endverbatim - - @ingroup constraints + vrna_gr_set_aux_exp_f(fc, cb) - @see vrna_message_constraint_options_all(), vrna_constraints_add(), #VRNA_CONSTRAINT_DB, - #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, - #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_INTRAMOL - @param option Option switch that tells which constraint help will be printed ### Prototype ```c -void vrna_message_constraint_options(unsigned int option); +int vrna_gr_set_aux_exp_f(vrna_fold_compound_t *fc, vrna_grammar_rule_f_exp cb); ``` """ -function vrna_message_constraint_options(option) - ccall((:vrna_message_constraint_options, libRNA), Cvoid, (Cuint,), option) +function vrna_gr_set_aux_exp_f(fc, cb) + ccall((:vrna_gr_set_aux_exp_f, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_exp), fc, cb) end """ - vrna_message_constraint_options_all() - - @brief Print structure constraint characters to stdout - (full constraint support) + vrna_gr_set_aux_c(fc, cb) - @ingroup constraints - @see vrna_message_constraint_options(), vrna_constraints_add(), #VRNA_CONSTRAINT_DB, - #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, - #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_INTRAMOL ### Prototype ```c -void vrna_message_constraint_options_all(void); +int vrna_gr_set_aux_c(vrna_fold_compound_t *fc, vrna_grammar_rule_f cb); ``` """ -function vrna_message_constraint_options_all() - ccall((:vrna_message_constraint_options_all, libRNA), Cvoid, ()) +function vrna_gr_set_aux_c(fc, cb) + ccall((:vrna_gr_set_aux_c, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f), fc, cb) end """ - vrna_hc_init(fc) - - @brief Initialize/Reset hard constraints to default values - - This function resets the hard constraints to their default values, i.e. - all positions may be unpaired in all contexts, and base pairs are - allowed in all contexts, if they resemble canonical pairs. - Previously set hard constraints will be removed before initialization. - - @ingroup hard_constraints + vrna_gr_set_aux_exp_c(fc, cb) - @see vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_add_up() - @param fc The fold compound ### Prototype ```c -void vrna_hc_init(vrna_fold_compound_t *fc); +int vrna_gr_set_aux_exp_c(vrna_fold_compound_t *fc, vrna_grammar_rule_f_exp cb); ``` """ -function vrna_hc_init(fc) - ccall((:vrna_hc_init, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_gr_set_aux_exp_c(fc, cb) + ccall((:vrna_gr_set_aux_exp_c, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_exp), fc, cb) end """ - vrna_hc_init_window(fc) + vrna_gr_set_aux_m(fc, cb) ### Prototype ```c -void vrna_hc_init_window(vrna_fold_compound_t *fc); +int vrna_gr_set_aux_m(vrna_fold_compound_t *fc, vrna_grammar_rule_f cb); ``` """ -function vrna_hc_init_window(fc) - ccall((:vrna_hc_init_window, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_gr_set_aux_m(fc, cb) + ccall((:vrna_gr_set_aux_m, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f), fc, cb) end """ - vrna_hc_prepare(fc, options) + vrna_gr_set_aux_exp_m(fc, cb) ### Prototype ```c -int vrna_hc_prepare(vrna_fold_compound_t *fc, unsigned int options); +int vrna_gr_set_aux_exp_m(vrna_fold_compound_t *fc, vrna_grammar_rule_f_exp cb); ``` """ -function vrna_hc_prepare(fc, options) - ccall((:vrna_hc_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) +function vrna_gr_set_aux_exp_m(fc, cb) + ccall((:vrna_gr_set_aux_exp_m, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_exp), fc, cb) end """ - vrna_hc_update(fc, i, options) + vrna_gr_set_aux_m1(fc, cb) ### Prototype ```c -void vrna_hc_update(vrna_fold_compound_t *fc, unsigned int i, unsigned int options); +int vrna_gr_set_aux_m1(vrna_fold_compound_t *fc, vrna_grammar_rule_f cb); ``` """ -function vrna_hc_update(fc, i, options) - ccall((:vrna_hc_update, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, i, options) +function vrna_gr_set_aux_m1(fc, cb) + ccall((:vrna_gr_set_aux_m1, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f), fc, cb) end """ - vrna_hc_add_up(fc, i, option) - - @brief Make a certain nucleotide unpaired - - @ingroup hard_constraints + vrna_gr_set_aux_exp_m1(fc, cb) - @see vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_init(), - #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, - #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, - #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - @param fc The #vrna_fold_compound_t the hard constraints are associated with - @param i The position that needs to stay unpaired (1-based) - @param option The options flag indicating how/where to store the hard constraints ### Prototype ```c -void vrna_hc_add_up(vrna_fold_compound_t *fc, int i, unsigned char option); +int vrna_gr_set_aux_exp_m1(vrna_fold_compound_t *fc, vrna_grammar_rule_f_exp cb); ``` """ -function vrna_hc_add_up(fc, i, option) - ccall((:vrna_hc_add_up, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, Cuchar), fc, i, option) +function vrna_gr_set_aux_exp_m1(fc, cb) + ccall((:vrna_gr_set_aux_exp_m1, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_exp), fc, cb) end """ - vrna_hc_add_up_strand(fc, i, strand, option) + vrna_gr_set_aux(fc, cb) ### Prototype ```c -int vrna_hc_add_up_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int strand, unsigned char option); +int vrna_gr_set_aux(vrna_fold_compound_t *fc, vrna_grammar_rule_f_aux cb); ``` """ -function vrna_hc_add_up_strand(fc, i, strand, option) - ccall((:vrna_hc_add_up_strand, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuchar), fc, i, strand, option) +function vrna_gr_set_aux(fc, cb) + ccall((:vrna_gr_set_aux, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_aux), fc, cb) end """ - vrna_hc_add_up_batch(fc, constraints) - - @brief Apply a list of hard constraints for single nucleotides + vrna_gr_set_aux_exp(fc, cb) - @ingroup hard_constraints - @param fc The #vrna_fold_compound_t the hard constraints are associated with - @param constraints The list off constraints to apply, last entry must have position - attribute set to 0 ### Prototype ```c -int vrna_hc_add_up_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints); +int vrna_gr_set_aux_exp(vrna_fold_compound_t *fc, vrna_grammar_rule_f_aux_exp cb); ``` """ -function vrna_hc_add_up_batch(fc, constraints) - ccall((:vrna_hc_add_up_batch, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_hc_up_t}), fc, constraints) +function vrna_gr_set_aux_exp(fc, cb) + ccall((:vrna_gr_set_aux_exp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_aux_exp), fc, cb) end """ - vrna_hc_add_up_strand_batch(fc, constraints) + vrna_gr_set_data(fc, data, free_data) ### Prototype ```c -int vrna_hc_add_up_strand_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints); +int vrna_gr_set_data(vrna_fold_compound_t *fc, void *data, vrna_grammar_data_free_f free_data); ``` """ -function vrna_hc_add_up_strand_batch(fc, constraints) - ccall((:vrna_hc_add_up_strand_batch, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_hc_up_t}), fc, constraints) +function vrna_gr_set_data(fc, data, free_data) + ccall((:vrna_gr_set_data, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_grammar_data_free_f), fc, data, free_data) end """ - vrna_hc_add_bp(fc, i, j, option) - - @brief Favorize/Enforce a certain base pair (i,j) - - @ingroup hard_constraints + vrna_gr_set_cond(fc, cb) - @see vrna_hc_add_bp_nonspecific(), vrna_hc_add_up(), vrna_hc_init(), - #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, - #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, - #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, - #VRNA_CONSTRAINT_CONTEXT_ENFORCE, #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - @param fc The #vrna_fold_compound_t the hard constraints are associated with - @param i The 5' located nucleotide position of the base pair (1-based) - @param j The 3' located nucleotide position of the base pair (1-based) - @param option The options flag indicating how/where to store the hard constraints ### Prototype ```c -int vrna_hc_add_bp(vrna_fold_compound_t *fc, int i, int j, unsigned char option); +int vrna_gr_set_cond(vrna_fold_compound_t *fc, vrna_grammar_cond_f cb); ``` """ -function vrna_hc_add_bp(fc, i, j, option) - ccall((:vrna_hc_add_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cint, Cuchar), fc, i, j, option) +function vrna_gr_set_cond(fc, cb) + ccall((:vrna_gr_set_cond, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_cond_f), fc, cb) end """ - vrna_hc_add_bp_strand(fc, i, strand_i, j, strand_j, option) + vrna_gr_reset(fc) ### Prototype ```c -int vrna_hc_add_bp_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int strand_i, unsigned int j, unsigned int strand_j, unsigned char option); +int vrna_gr_reset(vrna_fold_compound_t *fc); ``` """ -function vrna_hc_add_bp_strand(fc, i, strand_i, j, strand_j, option) - ccall((:vrna_hc_add_bp_strand, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Cuint, Cuchar), fc, i, strand_i, j, strand_j, option) +function vrna_gr_reset(fc) + ccall((:vrna_gr_reset, libRNA), Cint, (Ptr{vrna_fold_compound_t},), fc) end -""" - vrna_hc_add_bp_nonspecific(fc, i, d, option) +struct vrna_unstructured_domain_motif_s + start::Cint + number::Cint +end - @brief Enforce a nucleotide to be paired (upstream/downstream) +const vrna_ud_motif_t = vrna_unstructured_domain_motif_s - @ingroup hard_constraints +""" + vrna_hx_s - @see vrna_hc_add_bp(), vrna_hc_add_up(), vrna_hc_init(), - #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, - #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, - #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, - #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS + @brief Data structure representing an entry of a helix list +""" +struct vrna_hx_s + start::Cuint + _end::Cuint + length::Cuint + up5::Cuint + up3::Cuint +end - @param fc The #vrna_fold_compound_t the hard constraints are associated with - @param i The position that needs to stay unpaired (1-based) - @param d The direction of base pairing (@f\$ d < 0 @f\$: pairs upstream, - @f\$ d > 0 @f\$: pairs downstream, @f\$ d == 0 @f\$: no direction) - @param option The options flag indicating in which loop type context the pairs may appear -### Prototype -```c -void vrna_hc_add_bp_nonspecific(vrna_fold_compound_t *fc, int i, int d, unsigned char option); -``` """ -function vrna_hc_add_bp_nonspecific(fc, i, d, option) - ccall((:vrna_hc_add_bp_nonspecific, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, Cint, Cuchar), fc, i, d, option) -end + @brief Convenience typedef for data structure #vrna_hx_s + @ingroup struct_utils_helix_list +""" +const vrna_hx_t = vrna_hx_s """ - vrna_hc_free(hc) + @brief Convenience typedef for data structure #vrna_elem_prob_s + @ingroup struct_utils_plist +""" +const vrna_ep_t = vrna_elem_prob_s - @brief Free the memory allocated by a #vrna_hc_t data structure +""" + vrna_db_pack(struc) - Use this function to free all memory that was allocated for a data structure - of type #vrna_hc_t . + @brief Pack secondary secondary structure, 5:1 compression using base 3 encoding - @see get_hard_constraints(), #vrna_hc_t + Returns a binary string encoding of the secondary structure using + a 5:1 compression scheme. The string is NULL terminated and can + therefore be used with standard string functions such as strcmp(). + Useful for programs that need to keep many structures in memory. - @ingroup hard_constraints + @see vrna_db_unpack() + @param struc The secondary structure in dot-bracket notation + @return The binary encoded structure ### Prototype ```c -void vrna_hc_free(vrna_hc_t *hc); +char * vrna_db_pack(const char *struc); ``` """ -function vrna_hc_free(hc) - ccall((:vrna_hc_free, libRNA), Cvoid, (Ptr{vrna_hc_t},), hc) +function vrna_db_pack(struc) + ccall((:vrna_db_pack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), struc) end """ - vrna_hc_add_f(fc, f) + vrna_db_unpack(packed) - @brief Add a function pointer pointer for the generic hard constraint - feature + @brief Unpack secondary structure previously packed with vrna_db_pack() + + Translate a compressed binary string produced by vrna_db_pack() back into + the familiar dot-bracket notation. + + @see vrna_db_pack() + + @param packed The binary encoded packed secondary structure + @return The unpacked secondary structure in dot-bracket notation ### Prototype ```c -void vrna_hc_add_f(vrna_fold_compound_t *fc, vrna_hc_eval_f f); +char * vrna_db_unpack(const char *packed); ``` """ -function vrna_hc_add_f(fc, f) - ccall((:vrna_hc_add_f, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_hc_eval_f), fc, f) +function vrna_db_unpack(packed) + ccall((:vrna_db_unpack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), packed) end """ - vrna_hc_add_data(fc, data, f) + vrna_db_flatten(structure, options) - @brief Add an auxiliary data structure for the generic hard constraints callback function + @brief Substitute pairs of brackets in a string with parenthesis - @ingroup generic_hc + This function can be used to replace brackets of unusual types, + such as angular brackets @p <> , to dot-bracket format. + The @p options parameter is used tpo specify which types of brackets + will be replaced by round parenthesis @p () . - @see vrna_hc_add_f() + @see vrna_db_flatten_to(), + #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, + #VRNA_BRACKETS_DEFAULT - @param fc The fold compound the generic hard constraint function should be bound to - @param data A pointer to the data structure that holds required data for function 'f' - @param f A pointer to a function that free's the memory occupied by @p data (Maybe @p NULL) + @param structure The structure string where brackets are flattened in-place + @param options A bitmask to specify which types of brackets should be flattened out ### Prototype ```c -void vrna_hc_add_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f); +void vrna_db_flatten(char *structure, unsigned int options); ``` """ -function vrna_hc_add_data(fc, data, f) - ccall((:vrna_hc_add_data, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, f) +function vrna_db_flatten(structure, options) + ccall((:vrna_db_flatten, libRNA), Cvoid, (Ptr{Cchar}, Cuint), structure, options) end """ - vrna_hc_add_from_db(fc, constraint, options) + vrna_db_flatten_to(string, target, options) - @brief Add hard constraints from pseudo dot-bracket notation + @brief Substitute pairs of brackets in a string with another type of pair characters - This function allows one to apply hard constraints from a pseudo dot-bracket - notation. The @p options parameter controls, which characters are recognized - by the parser. Use the #VRNA_CONSTRAINT_DB_DEFAULT convenience macro, if you - want to allow all known characters + This function can be used to replace brackets in a structure annotation string, + such as square brackets @p [] , to another type of pair characters, + e.g. angular brackets @p <> . - @ingroup hard_constraints + The @p target array must contain a character for the 'pair open' annotation at + position 0, and one for 'pair close' at position 1. T@p options parameter is used + to specify which types of brackets will be replaced by the new pairs. - @see #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, - #VRNA_CONSTRAINT_DB_ANG_BRACK, #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTRAMOL, - #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_GQUAD + @see vrna_db_flatten(), + #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, + #VRNA_BRACKETS_DEFAULT - @param fc The fold compound - @param constraint A pseudo dot-bracket notation of the hard constraint. - @param options The option flags + @param string The structure string where brackets are flattened in-place + @param target The new pair characters the string will be flattened to + @param options A bitmask to specify which types of brackets should be flattened out ### Prototype ```c -int vrna_hc_add_from_db(vrna_fold_compound_t *fc, const char *constraint, unsigned int options); +void vrna_db_flatten_to(char *string, const char target[3], unsigned int options); ``` """ -function vrna_hc_add_from_db(fc, constraint, options) - ccall((:vrna_hc_add_from_db, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cuint), fc, constraint, options) +function vrna_db_flatten_to(string, target, options) + ccall((:vrna_db_flatten_to, libRNA), Cvoid, (Ptr{Cchar}, Ptr{Cchar}, Cuint), string, target, options) end """ - print_tty_constraint(option) + vrna_db_from_ptable(pt) + + @brief Convert a pair table into dot-parenthesis notation + + This function also converts pair table formatted structures that contain + pseudoknots. Non-nested base pairs result in additional pairs of + parenthesis and brackets within the resulting dot-parenthesis string. + The following pairs are awailable: (), []. {}. <>, as well as pairs of + matching upper-/lower-case characters from the alphabet A-Z. + @note In cases where the level of non-nested base pairs exceeds the + maximum number of 30 different base pair indicators (4 parenthesis/brackets, + 26 matching characters), a warning is printed and the remaining base pairs + are left out from the conversion. + @param pt The pair table to be copied + @return A char pointer to the dot-bracket string ### Prototype ```c -; +char * vrna_db_from_ptable(const short *pt); ``` """ -function print_tty_constraint(option) - ccall((:print_tty_constraint, libRNA), Cvoid, (Cuint,), option) +function vrna_db_from_ptable(pt) + ccall((:vrna_db_from_ptable, libRNA), Ptr{Cchar}, (Ptr{Cshort},), pt) end """ - print_tty_constraint_full() + vrna_db_from_plist(pairs, n) + + @brief Convert a list of base pairs into dot-bracket notation + @see vrna_plist() + @param pairs A #vrna_ep_t containing the pairs to be included in + the dot-bracket string + @param n The length of the structure (number of nucleotides) + @return The dot-bracket string containing the provided base pairs ### Prototype ```c -; +char * vrna_db_from_plist(vrna_ep_t *pairs, unsigned int n); ``` """ -function print_tty_constraint_full() - ccall((:print_tty_constraint_full, libRNA), Cvoid, ()) +function vrna_db_from_plist(pairs, n) + ccall((:vrna_db_from_plist, libRNA), Ptr{Cchar}, (Ptr{vrna_ep_t}, Cuint), pairs, n) end """ - constrain_ptypes(constraint, length, ptype, BP, min_loop_size, idx_type) + vrna_db_to_element_string(structure) + @brief Convert a secondary structure in dot-bracket notation to a nucleotide annotation of loop contexts + @param structure The secondary structure in dot-bracket notation + @return A string annotating each nucleotide according to it's structural context ### Prototype ```c -; +char * vrna_db_to_element_string(const char *structure); ``` """ -function constrain_ptypes(constraint, length, ptype, BP, min_loop_size, idx_type) - ccall((:constrain_ptypes, libRNA), Cvoid, (Ptr{Cchar}, Cuint, Ptr{Cchar}, Ptr{Cint}, Cint, Cuint), constraint, length, ptype, BP, min_loop_size, idx_type) +function vrna_db_to_element_string(structure) + ccall((:vrna_db_to_element_string, libRNA), Ptr{Cchar}, (Ptr{Cchar},), structure) end -# DEPRECATED -const vrna_callback_sc_energy = Cvoid - -# typedef int ( * vrna_sc_direct_f ) ( vrna_fold_compound_t * fc , int i , int j , int k , int l , void * data ) -const vrna_sc_direct_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_callback_sc_exp_energy = Cvoid - -# typedef FLT_OR_DBL ( * vrna_sc_exp_direct_f ) ( vrna_fold_compound_t * fc , int i , int j , int k , int l , void * data ) -const vrna_sc_exp_direct_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_callback_sc_backtrack = Cvoid - """ - vrna_sc_init(fc) + vrna_db_pk_remove(structure, options) - @brief Initialize an empty soft constraints data structure within a #vrna_fold_compound_t + @brief Remove pseudo-knots from an input structure - 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. + This function removes pseudo-knots from an input structure + by determining the minimum number of base pairs that need + to be removed to make the structure pseudo-knot free. - \\note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE + To accomplish that, we use a dynamic programming algorithm + similar to the Nussinov maxmimum matching approach. - @ingroup soft_constraints + The input structure must be in a dot-bracket string like form + where crossing base pairs are denoted by the use of additional + types of matching brackets, e.g. @p <>, @p {}, @p [], @p {}. + Furthermore, crossing pairs may be annotated by matching + uppercase/lowercase letters from the alphabet @p A-Z. For the latter, + the uppercase letter must be the 5' and the lowercase letter + the 3' nucleotide of the base pair. The actual type of brackets + to be recognized by this function must be specifed through the + @p options parameter. - @see 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 Brackets in the input structure string that are not covered + by the @p options bitmask will be silently ignored! - @param fc The #vrna_fold_compound_t where an empty soft constraint feature is to be added to + @see vrna_pt_pk_remove(), vrna_db_flatten(), + #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, + #VRNA_BRACKETS_ALPHA, #VRNA_BRACKETS_DEFAULT, #VRNA_BRACKETS_ANY + + @param structure Input structure in dot-bracket format that may include pseudo-knots + @param options A bitmask to specify which types of brackets should be processed + @return The input structure devoid of pseudo-knots in dot-bracket notation ### Prototype ```c -void vrna_sc_init(vrna_fold_compound_t *fc); +char * vrna_db_pk_remove(const char *structure, unsigned int options); ``` """ -function vrna_sc_init(fc) - ccall((:vrna_sc_init, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_db_pk_remove(structure, options) + ccall((:vrna_db_pk_remove, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cuint), structure, options) end """ - vrna_sc_prepare(fc, options) - + vrna_ptable(structure) -### Prototype -```c -int vrna_sc_prepare(vrna_fold_compound_t *fc, unsigned int options); -``` -""" -function vrna_sc_prepare(fc, options) - ccall((:vrna_sc_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) -end + @brief Create a pair table from a dot-bracket notation of a secondary structure -""" - vrna_sc_update(fc, i, options) + Returns a newly allocated table, such that table[i]=j if (i.j) pair + or 0 if i is unpaired, table[0] contains the length of the structure. + @see vrna_ptable_from_string(), vrna_db_from_ptable() + @param structure The secondary structure in dot-bracket notation + @return A pointer to the created pair_table ### Prototype ```c -int vrna_sc_update(vrna_fold_compound_t *fc, unsigned int i, unsigned int options); +short * vrna_ptable(const char *structure); ``` """ -function vrna_sc_update(fc, i, options) - ccall((:vrna_sc_update, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, i, options) +function vrna_ptable(structure) + ccall((:vrna_ptable, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_sc_set_bp(fc, constraints, options) - - @brief Set soft constraints for paired nucleotides + vrna_ptable_from_string(structure, options) - @note This function replaces any pre-exisitng soft constraints with the ones supplied - in @p constraints. + @brief Create a pair table for a secondary structure string - @ingroup soft_constraints + This function takes an input string of a secondary structure annotation + in @ref dot-bracket-notation or @ref dot-bracket-ext-notation, and converts + it into a pair table representation. - @see vrna_sc_add_bp(), vrna_sc_set_up(), vrna_sc_add_up() + @note This function also extracts crossing base pairs, i.e. pseudo-knots + if more than a single matching bracket type is allowed through the + bitmask @p options. - @param fc The #vrna_fold_compound_t the soft constraints are associated with - @param constraints A two-dimensional array of pseudo free energies in @f\$ kcal / mol @f\$ - @param options The options flag indicating how/where to store the soft constraints - @return Non-zero on successful application of the constraint, 0 otherwise. + @see vrna_ptable(), vrna_db_from_ptable(), vrna_db_flatten_to(), vrna_pt_pk_remove() + #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, + VRNA_BRACKETS_ALPHA, #VRNA_BRACKETS_DEFAULT, #VRNA_BRACKETS_ANY + + @param structure Secondary structure in @ref dot-bracket-ext-notation + @param options A bitmask to specify which brackets are recognized during conversion to pair table + @return A pointer to a new pair table of the provided secondary structure ### Prototype ```c -int vrna_sc_set_bp(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options); +short * vrna_ptable_from_string(const char *structure, unsigned int options); ``` """ -function vrna_sc_set_bp(fc, constraints, options) - ccall((:vrna_sc_set_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{FLT_OR_DBL}}, Cuint), fc, constraints, options) +function vrna_ptable_from_string(structure, options) + ccall((:vrna_ptable_from_string, libRNA), Ptr{Cshort}, (Ptr{Cchar}, Cuint), structure, options) end """ - vrna_sc_add_bp(fc, i, j, energy, options) + vrna_pt_pk_get(structure) - @brief Add soft constraints for paired nucleotides + @brief Create a pair table of a secondary structure (pseudo-knot version) - @ingroup soft_constraints + Returns a newly allocated table, such that table[i]=j if (i.j) pair + or 0 if i is unpaired, table[0] contains the length of the structure. - @see vrna_sc_set_bp(), vrna_sc_set_up(), vrna_sc_add_up() + In contrast to vrna_ptable() this function also recognizes the base pairs + denoted by '[' and ']' brackets. Thus, this function behaves like + @code{.c} + vrna_ptable_from_string(structure, VRNA_BRACKETS_RND | VRNA_BRACKETS_SQR) + @endcode - @param fc The #vrna_fold_compound_t the soft constraints are associated with - @param i The 5' position of the base pair the soft constraint is added for - @param j The 3' position of the base pair the soft constraint is added for - @param energy The free energy (soft-constraint) in @f\$ kcal / mol @f\$ - @param options The options flag indicating how/where to store the soft constraints - @return Non-zero on successful application of the constraint, 0 otherwise. + @see vrna_ptable_from_string() + + @param structure The secondary structure in (extended) dot-bracket notation + @return A pointer to the created pair_table ### Prototype ```c -int vrna_sc_add_bp(vrna_fold_compound_t *fc, int i, int j, FLT_OR_DBL energy, unsigned int options); +short * vrna_pt_pk_get(const char *structure); ``` """ -function vrna_sc_add_bp(fc, i, j, energy, options) - ccall((:vrna_sc_add_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cint, FLT_OR_DBL, Cuint), fc, i, j, energy, options) +function vrna_pt_pk_get(structure) + ccall((:vrna_pt_pk_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_sc_set_up(fc, constraints, options) - - @brief Set soft constraints for unpaired nucleotides - - @note This function replaces any pre-exisitng soft constraints with the ones supplied - in @p constraints. - - @ingroup soft_constraints + vrna_ptable_copy(pt) - @see vrna_sc_add_up(), vrna_sc_set_bp(), vrna_sc_add_bp() + @brief Get an exact copy of a pair table - @param fc The #vrna_fold_compound_t the soft constraints are associated with - @param constraints A vector of pseudo free energies in @f\$ kcal / mol @f\$ - @param options The options flag indicating how/where to store the soft constraints - @return Non-zero on successful application of the constraint, 0 otherwise. + @param pt The pair table to be copied + @return A pointer to the copy of 'pt' ### Prototype ```c -int vrna_sc_set_up(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options); +short * vrna_ptable_copy(const short *pt); ``` """ -function vrna_sc_set_up(fc, constraints, options) - ccall((:vrna_sc_set_up, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{FLT_OR_DBL}, Cuint), fc, constraints, options) +function vrna_ptable_copy(pt) + ccall((:vrna_ptable_copy, libRNA), Ptr{Cshort}, (Ptr{Cshort},), pt) end """ - vrna_sc_add_up(fc, i, energy, options) - - @brief Add soft constraints for unpaired nucleotides - - @ingroup soft_constraints + vrna_pt_ali_get(structure) - @see vrna_sc_set_up(), vrna_sc_add_bp(), vrna_sc_set_bp() +@brief Create a pair table of a secondary structure (snoop align version) - @param fc The #vrna_fold_compound_t the soft constraints are associated with - @param i The nucleotide position the soft constraint is added for - @param energy The free energy (soft-constraint) in @f\$ kcal / mol @f\$ - @param options The options flag indicating how/where to store the soft constraints - @return Non-zero on successful application of the constraint, 0 otherwise. ### Prototype ```c -int vrna_sc_add_up(vrna_fold_compound_t *fc, int i, FLT_OR_DBL energy, unsigned int options); +short * vrna_pt_ali_get(const char *structure); ``` """ -function vrna_sc_add_up(fc, i, energy, options) - ccall((:vrna_sc_add_up, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, FLT_OR_DBL, Cuint), fc, i, energy, options) +function vrna_pt_ali_get(structure) + ccall((:vrna_pt_ali_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_sc_set_stack(fc, constraints, options) + vrna_pt_snoop_get(structure) +@brief Create a pair table of a secondary structure (snoop version) + returns a newly allocated table, such that: table[i]=j if (i.j) pair or + 0 if i is unpaired, table[0] contains the length of the structure. + The special pseudoknotted H/ACA-mRNA structure is taken into account. ### Prototype ```c -int vrna_sc_set_stack(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options); +short * vrna_pt_snoop_get(const char *structure); ``` """ -function vrna_sc_set_stack(fc, constraints, options) - ccall((:vrna_sc_set_stack, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{FLT_OR_DBL}, Cuint), fc, constraints, options) +function vrna_pt_snoop_get(structure) + ccall((:vrna_pt_snoop_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_sc_set_stack_comparative(fc, constraints, options) + vrna_pt_pk_remove(ptable, options) + + @brief Remove pseudo-knots from a pair table + + This function removes pseudo-knots from an input structure + by determining the minimum number of base pairs that need + to be removed to make the structure pseudo-knot free. + + To accomplish that, we use a dynamic programming algorithm + similar to the Nussinov maxmimum matching approach. + @see vrna_db_pk_remove() + @param ptable Input structure that may include pseudo-knots + @param options + @return The input structure devoid of pseudo-knots ### Prototype ```c -int vrna_sc_set_stack_comparative(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options); +short * vrna_pt_pk_remove(const short *ptable, unsigned int options); ``` """ -function vrna_sc_set_stack_comparative(fc, constraints, options) - ccall((:vrna_sc_set_stack_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{FLT_OR_DBL}}, Cuint), fc, constraints, options) +function vrna_pt_pk_remove(ptable, options) + ccall((:vrna_pt_pk_remove, libRNA), Ptr{Cshort}, (Ptr{Cshort}, Cuint), ptable, options) end """ - vrna_sc_add_stack(fc, i, energy, options) + vrna_plist(struc, pr) + + @brief Create a #vrna_ep_t from a dot-bracket string + + The dot-bracket string is parsed and for each base pair an + entry in the plist is created. The probability of each pair in + the list is set by a function parameter. + The end of the plist is marked by sequence positions i as well as j + equal to 0. This condition should be used to stop looping over its + entries + @param struc The secondary structure in dot-bracket notation + @param pr The probability for each base pair used in the plist + @return The plist array ### Prototype ```c -int vrna_sc_add_stack(vrna_fold_compound_t *fc, int i, FLT_OR_DBL energy, unsigned int options); +vrna_ep_t *vrna_plist(const char *struc, float pr); ``` """ -function vrna_sc_add_stack(fc, i, energy, options) - ccall((:vrna_sc_add_stack, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, FLT_OR_DBL, Cuint), fc, i, energy, options) +function vrna_plist(struc, pr) + ccall((:vrna_plist, libRNA), Ptr{vrna_ep_t}, (Ptr{Cchar}, Cfloat), struc, pr) end """ - vrna_sc_add_stack_comparative(fc, i, energies, options) + vrna_plist_from_probs(fc, cut_off) + + @brief Create a #vrna_ep_t from base pair probability matrix + The probability matrix provided via the #vrna_fold_compound_t is parsed + and all pair probabilities above the given threshold are used to create + an entry in the plist + + The end of the plist is marked by sequence positions i as well as j + equal to 0. This condition should be used to stop looping over its + entries + @ingroup part_func_global + @param[in] fc The fold compound + @param[in] cut_off The cutoff value + @return A pointer to the plist that is to be created ### Prototype ```c -int vrna_sc_add_stack_comparative(vrna_fold_compound_t *fc, int i, const FLT_OR_DBL *energies, unsigned int options); +vrna_ep_t *vrna_plist_from_probs(vrna_fold_compound_t *fc, double cut_off); ``` """ -function vrna_sc_add_stack_comparative(fc, i, energies, options) - ccall((:vrna_sc_add_stack_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{FLT_OR_DBL}, Cuint), fc, i, energies, options) +function vrna_plist_from_probs(fc, cut_off) + ccall((:vrna_plist_from_probs, libRNA), Ptr{vrna_ep_t}, (Ptr{vrna_fold_compound_t}, Cdouble), fc, cut_off) end """ - vrna_sc_remove(fc) - - @brief Remove soft constraints from #vrna_fold_compound_t + vrna_db_from_WUSS(wuss) - @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE + @brief Convert a WUSS annotation string to dot-bracket format - @ingroup soft_constraints + @note This function flattens all brackets, and treats pseudo-knots annotated + by matching pairs of upper/lowercase letters as unpaired nucleotides - @param fc The #vrna_fold_compound_t possibly containing soft constraints + @param wuss The input string in WUSS notation + @return A dot-bracket notation of the input secondary structure ### Prototype ```c -void vrna_sc_remove(vrna_fold_compound_t *fc); +char * vrna_db_from_WUSS(const char *wuss); ``` """ -function vrna_sc_remove(fc) - ccall((:vrna_sc_remove, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_db_from_WUSS(wuss) + ccall((:vrna_db_from_WUSS, libRNA), Ptr{Cchar}, (Ptr{Cchar},), wuss) end """ - vrna_sc_free(sc) + vrna_abstract_shapes(structure, level) - @brief Free memory occupied by a #vrna_sc_t data structure + @brief Convert a secondary structure in dot-bracket notation to its abstract shapes representation - @ingroup soft_constraints + This function converts a secondary structure into its abstract shapes representation as + presented by @rstinline :cite:t:`giegerich:2004` @endrst. - @param sc The data structure to free from memory + @see vrna_abstract_shapes_pt() + + @param structure A secondary structure in dot-bracket notation + @param level The abstraction level (integer in the range of 0 to 5) + @return The secondary structure in abstract shapes notation ### Prototype ```c -void vrna_sc_free(vrna_sc_t *sc); +char * vrna_abstract_shapes(const char *structure, unsigned int level); ``` """ -function vrna_sc_free(sc) - ccall((:vrna_sc_free, libRNA), Cvoid, (Ptr{vrna_sc_t},), sc) +function vrna_abstract_shapes(structure, level) + ccall((:vrna_abstract_shapes, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cuint), structure, level) end """ - vrna_sc_add_data(fc, data, free_data) + vrna_abstract_shapes_pt(pt, level) - @brief Add an auxiliary data structure for the generic soft constraints callback function + @brief Convert a secondary structure to its abstract shapes representation - @ingroup soft_constraints + This function converts a secondary structure into its abstract shapes representation as + presented by @rstinline :cite:t:`giegerich:2004` @endrst. This function is equivalent to + vrna_db_to_shapes(), but requires a pair table input instead of a dot-bracket structure. - @see vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_bt() + @note The length of the structure must be present at @p pt[0]! - @param fc The fold compound the generic soft constraint function should be bound to - @param data A pointer to the data structure that holds required data for function 'f' - @param free_data A pointer to a function that free's the memory occupied by @p data (Maybe NULL) - @return Non-zero on successful binding the data (and free-function), 0 otherwise + @see vrna_abstract_shapes() + + @param pt A secondary structure in pair table format + @param level The abstraction level (integer in the range of 0 to 5) + @return The secondary structure in abstract shapes notation ### Prototype ```c -int vrna_sc_add_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f free_data); +char * vrna_abstract_shapes_pt(const short *pt, unsigned int level); ``` """ -function vrna_sc_add_data(fc, data, free_data) - ccall((:vrna_sc_add_data, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, free_data) +function vrna_abstract_shapes_pt(pt, level) + ccall((:vrna_abstract_shapes_pt, libRNA), Ptr{Cchar}, (Ptr{Cshort}, Cuint), pt, level) end """ - vrna_sc_add_auxdata(fc, data, prepare_cb, free_cb) + vrna_hx_from_ptable(pt) + @brief Convert a pair table representation of a secondary structure into a helix list + @param pt The secondary structure in pair table representation + @return The secondary structure represented as a helix list ### Prototype ```c -int vrna_sc_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_prepare_f prepare_cb, vrna_auxdata_free_f free_cb); +vrna_hx_t * vrna_hx_from_ptable(short *pt); ``` """ -function vrna_sc_add_auxdata(fc, data, prepare_cb, free_cb) - ccall((:vrna_sc_add_auxdata, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_prepare_f, vrna_auxdata_free_f), fc, data, prepare_cb, free_cb) +function vrna_hx_from_ptable(pt) + ccall((:vrna_hx_from_ptable, libRNA), Ptr{vrna_hx_t}, (Ptr{Cshort},), pt) end """ - vrna_sc_add_data_comparative(fc, data, free_data) - + vrna_hx_merge(list, maxdist) + @brief Create a merged helix list from another helix list ### Prototype ```c -int vrna_sc_add_data_comparative(vrna_fold_compound_t *fc, void **data, vrna_auxdata_free_f *free_data); +vrna_hx_t * vrna_hx_merge(const vrna_hx_t *list, int maxdist); ``` """ -function vrna_sc_add_data_comparative(fc, data, free_data) - ccall((:vrna_sc_add_data_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{Cvoid}}, Ptr{vrna_auxdata_free_f}), fc, data, free_data) +function vrna_hx_merge(list, maxdist) + ccall((:vrna_hx_merge, libRNA), Ptr{vrna_hx_t}, (Ptr{vrna_hx_t}, Cint), list, maxdist) end """ - vrna_sc_add_f(fc, f) - - @brief Bind a function pointer for generic soft constraint feature (MFE version) + vrna_loopidx_from_ptable(pt) - 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 @f\$ \\hat{E} @f\$ in @f\$ dacal/mol @f\$, where @f\$ 1 dacal/mol = 10 cal/mol @f\$. - - @ingroup soft_constraints - - @see vrna_sc_add_data(), vrna_sc_add_bt(), vrna_sc_add_exp_f() - - @param fc The fold compound the generic soft constraint function should be bound to - @param f A pointer to the function that evaluates the generic soft constraint feature - @return Non-zero on successful binding the callback function, 0 otherwise + @brief Get a loop index representation of a structure ### Prototype ```c -int vrna_sc_add_f(vrna_fold_compound_t *fc, vrna_sc_f f); +int * vrna_loopidx_from_ptable(const short *pt); ``` """ -function vrna_sc_add_f(fc, f) - ccall((:vrna_sc_add_f, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_f), fc, f) +function vrna_loopidx_from_ptable(pt) + ccall((:vrna_loopidx_from_ptable, libRNA), Ptr{Cint}, (Ptr{Cshort},), pt) end """ - vrna_sc_multi_cb_add(fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) + vrna_bp_distance_pt(pt1, pt2) + + @brief Compute the "base pair" distance between two pair tables pt1 and pt2 of secondary structures. + + The pair tables should have the same length. + dist = number of base pairs in one structure but not in the other + same as edit distance with open-pair close-pair as move-set + @see vrna_bp_distance() + @param pt1 First structure in dot-bracket notation + @param pt2 Second structure in dot-bracket notation + @return The base pair distance between pt1 and pt2 ### Prototype ```c -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); +int vrna_bp_distance_pt(const short *pt1, const short *pt2); ``` """ -function vrna_sc_multi_cb_add(fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) - ccall((:vrna_sc_multi_cb_add, libRNA), Csize_t, (Ptr{vrna_fold_compound_t}, vrna_sc_direct_f, vrna_sc_exp_direct_f, Ptr{Cvoid}, vrna_auxdata_prepare_f, vrna_auxdata_free_f, Cuint), fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) +function vrna_bp_distance_pt(pt1, pt2) + ccall((:vrna_bp_distance_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}), pt1, pt2) end """ - vrna_sc_add_f_comparative(fc, f) + vrna_bp_distance(str1, str2) + + @brief Compute the "base pair" distance between two secondary structures s1 and s2. + + This is a wrapper around @b vrna_bp_distance_pt(). + The sequences should have the same length. + dist = number of base pairs in one structure but not in the other + same as edit distance with open-pair close-pair as move-set + @see vrna_bp_distance_pt() + @param str1 First structure in dot-bracket notation + @param str2 Second structure in dot-bracket notation + @return The base pair distance between str1 and str2 ### Prototype ```c -int vrna_sc_add_f_comparative(vrna_fold_compound_t *fc, vrna_sc_f *f); +int vrna_bp_distance(const char *str1, const char *str2); ``` """ -function vrna_sc_add_f_comparative(fc, f) - ccall((:vrna_sc_add_f_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_sc_f}), fc, f) +function vrna_bp_distance(str1, str2) + ccall((:vrna_bp_distance, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}), str1, str2) end """ - vrna_sc_add_bt(fc, f) - - @brief Bind a backtracking function pointer for generic soft constraint feature - - 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. - - @ingroup soft_constraints + vrna_dist_mountain(str1, str2, p) - @see vrna_sc_add_data(), vrna_sc_add_f(), vrna_sc_add_exp_f() - @param fc The fold compound the generic soft constraint function should be bound to - @param f A pointer to the function that returns additional base pairs - @return Non-zero on successful binding the callback function, 0 otherwise ### Prototype ```c -int vrna_sc_add_bt(vrna_fold_compound_t *fc, vrna_sc_bt_f f); +double vrna_dist_mountain(const char *str1, const char *str2, unsigned int p); ``` """ -function vrna_sc_add_bt(fc, f) - ccall((:vrna_sc_add_bt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_bt_f), fc, f) +function vrna_dist_mountain(str1, str2, p) + ccall((:vrna_dist_mountain, libRNA), Cdouble, (Ptr{Cchar}, Ptr{Cchar}, Cuint), str1, str2, p) end """ - vrna_sc_add_exp_f(fc, exp_f) - - @brief Bind a function pointer for generic soft constraint feature (PF version) - - 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 @f\$ \\hat{E} @f\$ as Boltzmann factor, i.e. @f\$ exp(- \\hat{E} / kT) @f\$. - The required unit for @f\$ E @f\$ is @f\$ cal/mol @f\$. - - @ingroup soft_constraints + vrna_refBPcnt_matrix(reference_pt, turn) - @see vrna_sc_add_bt(), vrna_sc_add_f(), vrna_sc_add_data() + @brief Make a reference base pair count matrix - @param fc The fold compound the generic soft constraint function should be bound to - @param exp_f A pointer to the function that evaluates the generic soft constraint feature - @return Non-zero on successful binding the callback function, 0 otherwise + Get an upper triangular matrix containing the number of basepairs of a reference + structure for each interval [i,j] with iExpanded and HIT tree representations! + @see vrna_db_to_tree_string(), #VRNA_STRUCTURE_TREE_EXPANDED, #VRNA_STRUCTURE_TREE_HIT, + @ref sec_structure_representations_tree + @param tree A linear tree string representation of a secondary structure + @return A dot-bracket notation of the secondary structure provided in @p tree ### Prototype ```c -int vrna_gr_set_aux_m1(vrna_fold_compound_t *fc, vrna_grammar_rule_f cb); +char * vrna_tree_string_to_db(const char *tree); ``` """ -function vrna_gr_set_aux_m1(fc, cb) - ccall((:vrna_gr_set_aux_m1, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f), fc, cb) +function vrna_tree_string_to_db(tree) + ccall((:vrna_tree_string_to_db, libRNA), Ptr{Cchar}, (Ptr{Cchar},), tree) end """ - vrna_gr_set_aux_exp_m1(fc, cb) + assign_plist_from_db(pl, struc, pr) ### Prototype ```c -int vrna_gr_set_aux_exp_m1(vrna_fold_compound_t *fc, vrna_grammar_rule_f_exp cb); +; ``` """ -function vrna_gr_set_aux_exp_m1(fc, cb) - ccall((:vrna_gr_set_aux_exp_m1, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_exp), fc, cb) +function assign_plist_from_db(pl, struc, pr) + ccall((:assign_plist_from_db, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Ptr{Cchar}, Cfloat), pl, struc, pr) end """ - vrna_gr_set_aux(fc, cb) + pack_structure(struc) ### Prototype ```c -int vrna_gr_set_aux(vrna_fold_compound_t *fc, vrna_grammar_rule_f_aux cb); +; ``` """ -function vrna_gr_set_aux(fc, cb) - ccall((:vrna_gr_set_aux, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_aux), fc, cb) +function pack_structure(struc) + ccall((:pack_structure, libRNA), Ptr{Cchar}, (Ptr{Cchar},), struc) end """ - vrna_gr_set_aux_exp(fc, cb) + unpack_structure(packed) ### Prototype ```c -int vrna_gr_set_aux_exp(vrna_fold_compound_t *fc, vrna_grammar_rule_f_aux_exp cb); +; ``` """ -function vrna_gr_set_aux_exp(fc, cb) - ccall((:vrna_gr_set_aux_exp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_rule_f_aux_exp), fc, cb) +function unpack_structure(packed) + ccall((:unpack_structure, libRNA), Ptr{Cchar}, (Ptr{Cchar},), packed) end """ - vrna_gr_set_data(fc, data, free_data) + make_pair_table(structure) ### Prototype ```c -int vrna_gr_set_data(vrna_fold_compound_t *fc, void *data, vrna_grammar_data_free_f free_data); +; ``` """ -function vrna_gr_set_data(fc, data, free_data) - ccall((:vrna_gr_set_data, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_grammar_data_free_f), fc, data, free_data) +function make_pair_table(structure) + ccall((:make_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_gr_set_cond(fc, cb) + make_pair_table_pk(structure) ### Prototype ```c -int vrna_gr_set_cond(vrna_fold_compound_t *fc, vrna_grammar_cond_f cb); +; ``` """ -function vrna_gr_set_cond(fc, cb) - ccall((:vrna_gr_set_cond, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_grammar_cond_f), fc, cb) +function make_pair_table_pk(structure) + ccall((:make_pair_table_pk, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - vrna_gr_reset(fc) + copy_pair_table(pt) ### Prototype ```c -int vrna_gr_reset(vrna_fold_compound_t *fc); +; ``` """ -function vrna_gr_reset(fc) - ccall((:vrna_gr_reset, libRNA), Cint, (Ptr{vrna_fold_compound_t},), fc) -end - -struct vrna_unstructured_domain_motif_s - start::Cint - number::Cint +function copy_pair_table(pt) + ccall((:copy_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cshort},), pt) end -const vrna_ud_motif_t = vrna_unstructured_domain_motif_s - """ - vrna_hx_s + alimake_pair_table(structure) - @brief Data structure representing an entry of a helix list + +### Prototype +```c +; +``` """ -struct vrna_hx_s - start::Cuint - _end::Cuint - length::Cuint - up5::Cuint - up3::Cuint +function alimake_pair_table(structure) + ccall((:alimake_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) end """ - @brief Convenience typedef for data structure #vrna_hx_s - @ingroup struct_utils_helix_list -""" -const vrna_hx_t = vrna_hx_s + make_pair_table_snoop(structure) -""" - @brief Convenience typedef for data structure #vrna_elem_prob_s - @ingroup struct_utils_plist -""" -const vrna_ep_t = vrna_elem_prob_s +### Prototype +```c +; +``` """ - vrna_db_pack(struc) - - @brief Pack secondary secondary structure, 5:1 compression using base 3 encoding +function make_pair_table_snoop(structure) + ccall((:make_pair_table_snoop, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +end - Returns a binary string encoding of the secondary structure using - a 5:1 compression scheme. The string is NULL terminated and can - therefore be used with standard string functions such as strcmp(). - Useful for programs that need to keep many structures in memory. +""" + make_loop_index_pt(pt) - @see vrna_db_unpack() - @param struc The secondary structure in dot-bracket notation - @return The binary encoded structure ### Prototype ```c -char * vrna_db_pack(const char *struc); +; ``` """ -function vrna_db_pack(struc) - ccall((:vrna_db_pack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), struc) +function make_loop_index_pt(pt) + ccall((:make_loop_index_pt, libRNA), Ptr{Cint}, (Ptr{Cshort},), pt) end """ - vrna_db_unpack(packed) - - @brief Unpack secondary structure previously packed with vrna_db_pack() - - Translate a compressed binary string produced by vrna_db_pack() back into - the familiar dot-bracket notation. + bp_distance(str1, str2) - @see vrna_db_pack() - @param packed The binary encoded packed secondary structure - @return The unpacked secondary structure in dot-bracket notation ### Prototype ```c -char * vrna_db_unpack(const char *packed); +; ``` """ -function vrna_db_unpack(packed) - ccall((:vrna_db_unpack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), packed) +function bp_distance(str1, str2) + ccall((:bp_distance, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}), str1, str2) end """ - vrna_db_flatten(structure, options) - - @brief Substitute pairs of brackets in a string with parenthesis - - This function can be used to replace brackets of unusual types, - such as angular brackets @p <> , to dot-bracket format. - The @p options parameter is used tpo specify which types of brackets - will be replaced by round parenthesis @p () . + make_referenceBP_array(reference_pt, turn) - @see vrna_db_flatten_to(), - #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, - #VRNA_BRACKETS_DEFAULT - @param structure The structure string where brackets are flattened in-place - @param options A bitmask to specify which types of brackets should be flattened out ### Prototype ```c -void vrna_db_flatten(char *structure, unsigned int options); +; ``` """ -function vrna_db_flatten(structure, options) - ccall((:vrna_db_flatten, libRNA), Cvoid, (Ptr{Cchar}, Cuint), structure, options) +function make_referenceBP_array(reference_pt, turn) + ccall((:make_referenceBP_array, libRNA), Ptr{Cuint}, (Ptr{Cshort}, Cuint), reference_pt, turn) end """ - vrna_db_flatten_to(string, target, options) - - @brief Substitute pairs of brackets in a string with another type of pair characters - - This function can be used to replace brackets in a structure annotation string, - such as square brackets @p [] , to another type of pair characters, - e.g. angular brackets @p <> . - - The @p target array must contain a character for the 'pair open' annotation at - position 0, and one for 'pair close' at position 1. T@p options parameter is used - to specify which types of brackets will be replaced by the new pairs. + compute_BPdifferences(pt1, pt2, turn) - @see vrna_db_flatten(), - #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, - #VRNA_BRACKETS_DEFAULT - @param string The structure string where brackets are flattened in-place - @param target The new pair characters the string will be flattened to - @param options A bitmask to specify which types of brackets should be flattened out ### Prototype ```c -void vrna_db_flatten_to(char *string, const char target[3], unsigned int options); +; ``` """ -function vrna_db_flatten_to(string, target, options) - ccall((:vrna_db_flatten_to, libRNA), Cvoid, (Ptr{Cchar}, Ptr{Cchar}, Cuint), string, target, options) +function compute_BPdifferences(pt1, pt2, turn) + ccall((:compute_BPdifferences, libRNA), Ptr{Cuint}, (Ptr{Cshort}, Ptr{Cshort}, Cuint), pt1, pt2, turn) end """ - vrna_db_from_ptable(pt) - - @brief Convert a pair table into dot-parenthesis notation - - This function also converts pair table formatted structures that contain - pseudoknots. Non-nested base pairs result in additional pairs of - parenthesis and brackets within the resulting dot-parenthesis string. - The following pairs are awailable: (), []. {}. <>, as well as pairs of - matching upper-/lower-case characters from the alphabet A-Z. + assign_plist_from_pr(pl, probs, length, cutoff) - @note In cases where the level of non-nested base pairs exceeds the - maximum number of 30 different base pair indicators (4 parenthesis/brackets, - 26 matching characters), a warning is printed and the remaining base pairs - are left out from the conversion. - @param pt The pair table to be copied - @return A char pointer to the dot-bracket string ### Prototype ```c -char * vrna_db_from_ptable(const short *pt); +; ``` """ -function vrna_db_from_ptable(pt) - ccall((:vrna_db_from_ptable, libRNA), Ptr{Cchar}, (Ptr{Cshort},), pt) +function assign_plist_from_pr(pl, probs, length, cutoff) + ccall((:assign_plist_from_pr, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Ptr{FLT_OR_DBL}, Cint, Cdouble), pl, probs, length, cutoff) end """ - vrna_db_from_plist(pairs, n) - - @brief Convert a list of base pairs into dot-bracket notation + parenthesis_structure(structure, bp, length) - @see vrna_plist() - @param pairs A #vrna_ep_t containing the pairs to be included in - the dot-bracket string - @param n The length of the structure (number of nucleotides) - @return The dot-bracket string containing the provided base pairs ### Prototype ```c -char * vrna_db_from_plist(vrna_ep_t *pairs, unsigned int n); +; ``` """ -function vrna_db_from_plist(pairs, n) - ccall((:vrna_db_from_plist, libRNA), Ptr{Cchar}, (Ptr{vrna_ep_t}, Cuint), pairs, n) +function parenthesis_structure(structure, bp, length) + ccall((:parenthesis_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) end """ - vrna_db_to_element_string(structure) + parenthesis_zuker(structure, bp, length) - @brief Convert a secondary structure in dot-bracket notation to a nucleotide annotation of loop contexts - @param structure The secondary structure in dot-bracket notation - @return A string annotating each nucleotide according to it's structural context ### Prototype ```c -char * vrna_db_to_element_string(const char *structure); +; ``` """ -function vrna_db_to_element_string(structure) - ccall((:vrna_db_to_element_string, libRNA), Ptr{Cchar}, (Ptr{Cchar},), structure) +function parenthesis_zuker(structure, bp, length) + ccall((:parenthesis_zuker, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) end """ - vrna_db_pk_remove(structure, options) - - @brief Remove pseudo-knots from an input structure - - This function removes pseudo-knots from an input structure - by determining the minimum number of base pairs that need - to be removed to make the structure pseudo-knot free. - - To accomplish that, we use a dynamic programming algorithm - similar to the Nussinov maxmimum matching approach. - - The input structure must be in a dot-bracket string like form - where crossing base pairs are denoted by the use of additional - types of matching brackets, e.g. @p <>, @p {}, @p [], @p {}. - Furthermore, crossing pairs may be annotated by matching - uppercase/lowercase letters from the alphabet @p A-Z. For the latter, - the uppercase letter must be the 5' and the lowercase letter - the 3' nucleotide of the base pair. The actual type of brackets - to be recognized by this function must be specifed through the - @p options parameter. - - @note Brackets in the input structure string that are not covered - by the @p options bitmask will be silently ignored! + letter_structure(structure, bp, length) - @see vrna_pt_pk_remove(), vrna_db_flatten(), - #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, - #VRNA_BRACKETS_ALPHA, #VRNA_BRACKETS_DEFAULT, #VRNA_BRACKETS_ANY - @param structure Input structure in dot-bracket format that may include pseudo-knots - @param options A bitmask to specify which types of brackets should be processed - @return The input structure devoid of pseudo-knots in dot-bracket notation ### Prototype ```c -char * vrna_db_pk_remove(const char *structure, unsigned int options); +; ``` """ -function vrna_db_pk_remove(structure, options) - ccall((:vrna_db_pk_remove, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cuint), structure, options) +function letter_structure(structure, bp, length) + ccall((:letter_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) end """ - vrna_ptable(structure) - - @brief Create a pair table from a dot-bracket notation of a secondary structure - - Returns a newly allocated table, such that table[i]=j if (i.j) pair - or 0 if i is unpaired, table[0] contains the length of the structure. + bppm_to_structure(structure, pr, length) - @see vrna_ptable_from_string(), vrna_db_from_ptable() - @param structure The secondary structure in dot-bracket notation - @return A pointer to the created pair_table ### Prototype ```c -short * vrna_ptable(const char *structure); +; ``` """ -function vrna_ptable(structure) - ccall((:vrna_ptable, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function bppm_to_structure(structure, pr, length) + ccall((:bppm_to_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{FLT_OR_DBL}, Cuint), structure, pr, length) end """ - vrna_ptable_from_string(structure, options) - - @brief Create a pair table for a secondary structure string - - This function takes an input string of a secondary structure annotation - in @ref dot-bracket-notation or @ref dot-bracket-ext-notation, and converts - it into a pair table representation. - - @note This function also extracts crossing base pairs, i.e. pseudo-knots - if more than a single matching bracket type is allowed through the - bitmask @p options. + bppm_symbol(x) - @see vrna_ptable(), vrna_db_from_ptable(), vrna_db_flatten_to(), vrna_pt_pk_remove() - #VRNA_BRACKETS_RND, #VRNA_BRACKETS_ANG, #VRNA_BRACKETS_CLY, #VRNA_BRACKETS_SQR, - VRNA_BRACKETS_ALPHA, #VRNA_BRACKETS_DEFAULT, #VRNA_BRACKETS_ANY - @param structure Secondary structure in @ref dot-bracket-ext-notation - @param options A bitmask to specify which brackets are recognized during conversion to pair table - @return A pointer to a new pair table of the provided secondary structure ### Prototype ```c -short * vrna_ptable_from_string(const char *structure, unsigned int options); +; ``` """ -function vrna_ptable_from_string(structure, options) - ccall((:vrna_ptable_from_string, libRNA), Ptr{Cshort}, (Ptr{Cchar}, Cuint), structure, options) +function bppm_symbol(x) + ccall((:bppm_symbol, libRNA), Cchar, (Ptr{Cfloat},), x) end -""" - vrna_pt_pk_get(structure) +# DEPRECATED +const vrna_callback_ud_energy = Cvoid - @brief Create a pair table of a secondary structure (pseudo-knot version) +# DEPRECATED +const vrna_callback_ud_exp_energy = Cvoid - Returns a newly allocated table, such that table[i]=j if (i.j) pair - or 0 if i is unpaired, table[0] contains the length of the structure. +# DEPRECATED +const vrna_callback_ud_production = Cvoid - In contrast to vrna_ptable() this function also recognizes the base pairs - denoted by '[' and ']' brackets. Thus, this function behaves like - @code{.c} - vrna_ptable_from_string(structure, VRNA_BRACKETS_RND | VRNA_BRACKETS_SQR) - @endcode +# DEPRECATED +const vrna_callback_ud_exp_production = Cvoid - @see vrna_ptable_from_string() +# DEPRECATED +const vrna_callback_ud_probs_add = Cvoid - @param structure The secondary structure in (extended) dot-bracket notation - @return A pointer to the created pair_table -### Prototype -```c -short * vrna_pt_pk_get(const char *structure); -``` -""" -function vrna_pt_pk_get(structure) - ccall((:vrna_pt_pk_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) -end +# DEPRECATED +const vrna_callback_ud_probs_get = Cvoid """ - vrna_ptable_copy(pt) + vrna_ud_motifs_centroid(fc, structure) - @brief Get an exact copy of a pair table + @brief Detect unstructured domains in centroid structure - @param pt The pair table to be copied - @return A pointer to the copy of 'pt' + Given a centroid structure and a set of unstructured domains compute + the list of unstructured domain motifs present in the centroid. + Since we do not explicitly annotate unstructured domain motifs in + dot-bracket strings, this function can be used to check for the + presence and location of unstructured domain motifs under the + assumption that the dot-bracket string is the centroid structure + of the equiibrium ensemble. + + @see vrna_centroid() + + @ingroup domains_up + + @param fc The fold_compound data structure with pre-computed equilibrium probabilities and model settings + @param structure The centroid structure in dot-bracket notation + @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list with + @p start=0, @p number=-1 ### Prototype ```c -short * vrna_ptable_copy(const short *pt); +vrna_ud_motif_t * vrna_ud_motifs_centroid(vrna_fold_compound_t *fc, const char *structure); ``` """ -function vrna_ptable_copy(pt) - ccall((:vrna_ptable_copy, libRNA), Ptr{Cshort}, (Ptr{Cshort},), pt) +function vrna_ud_motifs_centroid(fc, structure) + ccall((:vrna_ud_motifs_centroid, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - vrna_pt_ali_get(structure) + vrna_ud_motifs_MEA(fc, structure, probability_list) -@brief Create a pair table of a secondary structure (snoop align version) + @brief Detect unstructured domains in MEA structure + + Given an MEA structure and a set of unstructured domains compute + the list of unstructured domain motifs present in the MEA structure. + Since we do not explicitly annotate unstructured domain motifs in + dot-bracket strings, this function can be used to check for the + presence and location of unstructured domain motifs under the + assumption that the dot-bracket string is the MEA structure + of the equiibrium ensemble. + + @see MEA() + + @ingroup domains_up + @param fc The fold_compound data structure with pre-computed equilibrium probabilities and model settings + @param structure The MEA structure in dot-bracket notation + @param probability_list The list of probabilities to extract the MEA structure from + @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list + with @p start=0, @p number=-1 ### Prototype ```c -short * vrna_pt_ali_get(const char *structure); +vrna_ud_motif_t * vrna_ud_motifs_MEA(vrna_fold_compound_t *fc, const char *structure, vrna_ep_t *probability_list); ``` """ -function vrna_pt_ali_get(structure) - ccall((:vrna_pt_ali_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function vrna_ud_motifs_MEA(fc, structure, probability_list) + ccall((:vrna_ud_motifs_MEA, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{vrna_ep_t}), fc, structure, probability_list) end """ - vrna_pt_snoop_get(structure) + vrna_ud_motifs_MFE(fc, structure) -@brief Create a pair table of a secondary structure (snoop version) + @brief Detect unstructured domains in MFE structure - returns a newly allocated table, such that: table[i]=j if (i.j) pair or - 0 if i is unpaired, table[0] contains the length of the structure. - The special pseudoknotted H/ACA-mRNA structure is taken into account. + Given an MFE structure and a set of unstructured domains compute + the list of unstructured domain motifs present in the MFE structure. + Since we do not explicitly annotate unstructured domain motifs in + dot-bracket strings, this function can be used to check for the + presence and location of unstructured domain motifs under the + assumption that the dot-bracket string is the MFE structure + of the equiibrium ensemble. + + @see vrna_mfe() + + @ingroup domains_up + + @param fc The fold_compound data structure with model settings + @param structure The MFE structure in dot-bracket notation + @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list with @p start=0, @p number=-1 ### Prototype ```c -short * vrna_pt_snoop_get(const char *structure); +vrna_ud_motif_t * vrna_ud_motifs_MFE(vrna_fold_compound_t *fc, const char *structure); ``` """ -function vrna_pt_snoop_get(structure) - ccall((:vrna_pt_snoop_get, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function vrna_ud_motifs_MFE(fc, structure) + ccall((:vrna_ud_motifs_MFE, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - vrna_pt_pk_remove(ptable, options) + vrna_ud_add_motif(fc, motif, motif_en, motif_name, loop_type) - @brief Remove pseudo-knots from a pair table + @brief Add an unstructured domain motif, e.g. for ligand binding - This function removes pseudo-knots from an input structure - by determining the minimum number of base pairs that need - to be removed to make the structure pseudo-knot free. + This function adds a ligand binding motif and the associated binding free energy + to the #vrna_ud_t attribute of a #vrna_fold_compound_t. The motif data + will then be used in subsequent secondary structure predictions. Multiple calls + to this function with different motifs append all additional data to a list of + ligands, which all will be evaluated. Ligand motif data can be removed from the + #vrna_fold_compound_t again using the vrna_ud_remove() function. The loop + type parameter allows one to limit the ligand binding to particular loop type, + such as the exterior loop, hairpin loops, interior loops, or multibranch loops. - To accomplish that, we use a dynamic programming algorithm - similar to the Nussinov maxmimum matching approach. + @see #VRNA_UNSTRUCTURED_DOMAIN_EXT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_HP_LOOP, + #VRNA_UNSTRUCTURED_DOMAIN_INT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_MB_LOOP, + #VRNA_UNSTRUCTURED_DOMAIN_ALL_LOOPS, vrna_ud_remove() - @see vrna_db_pk_remove() + @ingroup domains_up + + @param fc The #vrna_fold_compound_t data structure the ligand motif should be bound to + @param motif The sequence motif the ligand binds to + @param motif_en The binding free energy of the ligand in kcal/mol + @param motif_name The name/id of the motif (may be @p NULL) + @param loop_type The loop type the ligand binds to - @param ptable Input structure that may include pseudo-knots - @param options - @return The input structure devoid of pseudo-knots ### Prototype ```c -short * vrna_pt_pk_remove(const short *ptable, unsigned int options); +void vrna_ud_add_motif(vrna_fold_compound_t *fc, const char *motif, double motif_en, const char *motif_name, unsigned int loop_type); ``` """ -function vrna_pt_pk_remove(ptable, options) - ccall((:vrna_pt_pk_remove, libRNA), Ptr{Cshort}, (Ptr{Cshort}, Cuint), ptable, options) +function vrna_ud_add_motif(fc, motif, motif_en, motif_name, loop_type) + ccall((:vrna_ud_add_motif, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cdouble, Ptr{Cchar}, Cuint), fc, motif, motif_en, motif_name, loop_type) end """ - vrna_plist(struc, pr) - - @brief Create a #vrna_ep_t from a dot-bracket string - - The dot-bracket string is parsed and for each base pair an - entry in the plist is created. The probability of each pair in - the list is set by a function parameter. + vrna_ud_get_motif_size_at(fc, i, loop_type) - The end of the plist is marked by sequence positions i as well as j - equal to 0. This condition should be used to stop looping over its - entries + @brief Get a list of unique motif sizes that start at a certain position within the sequence - @param struc The secondary structure in dot-bracket notation - @param pr The probability for each base pair used in the plist - @return The plist array ### Prototype ```c -vrna_ep_t *vrna_plist(const char *struc, float pr); +int *vrna_ud_get_motif_size_at(vrna_fold_compound_t *fc, int i, unsigned int loop_type); ``` """ -function vrna_plist(struc, pr) - ccall((:vrna_plist, libRNA), Ptr{vrna_ep_t}, (Ptr{Cchar}, Cfloat), struc, pr) +function vrna_ud_get_motif_size_at(fc, i, loop_type) + ccall((:vrna_ud_get_motif_size_at, libRNA), Ptr{Cint}, (Ptr{vrna_fold_compound_t}, Cint, Cuint), fc, i, loop_type) end """ - vrna_plist_from_probs(fc, cut_off) - - @brief Create a #vrna_ep_t from base pair probability matrix - - The probability matrix provided via the #vrna_fold_compound_t is parsed - and all pair probabilities above the given threshold are used to create - an entry in the plist + vrna_ud_get_motifs_at(fc, i, loop_type) - The end of the plist is marked by sequence positions i as well as j - equal to 0. This condition should be used to stop looping over its - entries - @ingroup part_func_global - @param[in] fc The fold compound - @param[in] cut_off The cutoff value - @return A pointer to the plist that is to be created ### Prototype ```c -vrna_ep_t *vrna_plist_from_probs(vrna_fold_compound_t *fc, double cut_off); +int * vrna_ud_get_motifs_at(vrna_fold_compound_t *fc, int i, unsigned int loop_type); ``` """ -function vrna_plist_from_probs(fc, cut_off) - ccall((:vrna_plist_from_probs, libRNA), Ptr{vrna_ep_t}, (Ptr{vrna_fold_compound_t}, Cdouble), fc, cut_off) +function vrna_ud_get_motifs_at(fc, i, loop_type) + ccall((:vrna_ud_get_motifs_at, libRNA), Ptr{Cint}, (Ptr{vrna_fold_compound_t}, Cint, Cuint), fc, i, loop_type) end """ - vrna_db_from_WUSS(wuss) - - @brief Convert a WUSS annotation string to dot-bracket format + vrna_ud_detect_motifs(fc, structure) - @note This function flattens all brackets, and treats pseudo-knots annotated - by matching pairs of upper/lowercase letters as unpaired nucleotides - @param wuss The input string in WUSS notation - @return A dot-bracket notation of the input secondary structure ### Prototype ```c -char * vrna_db_from_WUSS(const char *wuss); +vrna_ud_motif_t * vrna_ud_detect_motifs(vrna_fold_compound_t *fc, const char *structure); ``` """ -function vrna_db_from_WUSS(wuss) - ccall((:vrna_db_from_WUSS, libRNA), Ptr{Cchar}, (Ptr{Cchar},), wuss) +function vrna_ud_detect_motifs(fc, structure) + ccall((:vrna_ud_detect_motifs, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - vrna_abstract_shapes(structure, level) + vrna_ud_remove(fc) - @brief Convert a secondary structure in dot-bracket notation to its abstract shapes representation + @brief Remove ligand binding to unpaired stretches - This function converts a secondary structure into its abstract shapes representation as - presented by @rstinline :cite:t:`giegerich:2004` @endrst. + This function removes all ligand motifs that were bound to a #vrna_fold_compound_t using + the vrna_ud_add_motif() function. - @see vrna_abstract_shapes_pt() + @ingroup domains_up - @param structure A secondary structure in dot-bracket notation - @param level The abstraction level (integer in the range of 0 to 5) - @return The secondary structure in abstract shapes notation + @param fc The #vrna_fold_compound_t data structure the ligand motif data should be removed from ### Prototype ```c -char * vrna_abstract_shapes(const char *structure, unsigned int level); +void vrna_ud_remove(vrna_fold_compound_t *fc); ``` """ -function vrna_abstract_shapes(structure, level) - ccall((:vrna_abstract_shapes, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cuint), structure, level) +function vrna_ud_remove(fc) + ccall((:vrna_ud_remove, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_abstract_shapes_pt(pt, level) + vrna_ud_set_data(fc, data, free_cb) - @brief Convert a secondary structure to its abstract shapes representation + @brief Attach an auxiliary data structure - This function converts a secondary structure into its abstract shapes representation as - presented by @rstinline :cite:t:`giegerich:2004` @endrst. This function is equivalent to - vrna_db_to_shapes(), but requires a pair table input instead of a dot-bracket structure. + This function binds an arbitrary, auxiliary data structure for user-implemented ligand binding. + The optional callback @p free_cb will be passed the bound data structure whenever the #vrna_fold_compound_t + is removed from memory to avoid memory leaks. - @note The length of the structure must be present at @p pt[0]! + @see vrna_ud_set_prod_rule_cb(), vrna_ud_set_exp_prod_rule_cb(), + vrna_ud_remove() - @see vrna_abstract_shapes() + @ingroup domains_up - @param pt A secondary structure in pair table format - @param level The abstraction level (integer in the range of 0 to 5) - @return The secondary structure in abstract shapes notation + @param fc The #vrna_fold_compound_t data structure the auxiliary data structure should be bound to + @param data A pointer to the auxiliary data structure + @param free_cb A pointer to a callback function that free's memory occupied by @p data ### Prototype ```c -char * vrna_abstract_shapes_pt(const short *pt, unsigned int level); +void vrna_ud_set_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f free_cb); ``` """ -function vrna_abstract_shapes_pt(pt, level) - ccall((:vrna_abstract_shapes_pt, libRNA), Ptr{Cchar}, (Ptr{Cshort}, Cuint), pt, level) +function vrna_ud_set_data(fc, data, free_cb) + ccall((:vrna_ud_set_data, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, free_cb) end """ - vrna_hx_from_ptable(pt) + vrna_ud_set_prod_rule_cb(fc, pre_cb, e_cb) - @brief Convert a pair table representation of a secondary structure into a helix list + @brief Attach production rule callbacks for free energies computations - @param pt The secondary structure in pair table representation - @return The secondary structure represented as a helix list -### Prototype -```c -vrna_hx_t * vrna_hx_from_ptable(short *pt); -``` -""" -function vrna_hx_from_ptable(pt) - ccall((:vrna_hx_from_ptable, libRNA), Ptr{vrna_hx_t}, (Ptr{Cshort},), pt) -end + Use this function to bind a user-implemented grammar extension for unstructured + domains. -""" - vrna_hx_merge(list, maxdist) + The callback @p e_cb needs to evaluate the free energy contribution @f\$f(i,j)@f\$ of + the unpaired segment @f\$[i,j]@f\$. It will be executed in each of the regular secondary + structure production rules. Whenever the callback is passed the #VRNA_UNSTRUCTURED_DOMAIN_MOTIF + flag via its @p loop_type parameter the contribution of any ligand that consecutively + binds from position @f\$i@f\$ to @f\$j@f\$ (the white box) is requested. Otherwise, the callback + usually performs a lookup in the precomputed @p B matrices. Which @p B matrix is + addressed will be indicated by the flags #VRNA_UNSTRUCTURED_DOMAIN_EXT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_HP_LOOP + #VRNA_UNSTRUCTURED_DOMAIN_INT_LOOP, and #VRNA_UNSTRUCTURED_DOMAIN_MB_LOOP. As their names already imply, + they specify exterior loops (@p F production rule), hairpin loops and interior loops + (@p C production rule), and multibranch loops (@p M and @p M1 production rule). - @brief Create a merged helix list from another helix list -### Prototype -```c -vrna_hx_t * vrna_hx_merge(const vrna_hx_t *list, int maxdist); -``` -""" -function vrna_hx_merge(list, maxdist) - ccall((:vrna_hx_merge, libRNA), Ptr{vrna_hx_t}, (Ptr{vrna_hx_t}, Cint), list, maxdist) -end + @image xml ligands_up_callback.svg -""" - vrna_loopidx_from_ptable(pt) + The @p pre_cb callback will be executed as a pre-processing step right before the + regular secondary structure rules. Usually one would use this callback to fill the + dynamic programming matrices @p U and preparations of the auxiliary data structure + #vrna_unstructured_domain_s.data - @brief Get a loop index representation of a structure + @image xml B_prod_rule.svg + + @ingroup domains_up + + @param fc The #vrna_fold_compound_t data structure the callback will be bound to + @param pre_cb A pointer to a callback function for the @p B production rule + @param e_cb A pointer to a callback function for free energy evaluation ### Prototype ```c -int * vrna_loopidx_from_ptable(const short *pt); +void vrna_ud_set_prod_rule_cb(vrna_fold_compound_t *fc, vrna_ud_production_f pre_cb, vrna_ud_f e_cb); ``` """ -function vrna_loopidx_from_ptable(pt) - ccall((:vrna_loopidx_from_ptable, libRNA), Ptr{Cint}, (Ptr{Cshort},), pt) +function vrna_ud_set_prod_rule_cb(fc, pre_cb, e_cb) + ccall((:vrna_ud_set_prod_rule_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_production_f, vrna_ud_f), fc, pre_cb, e_cb) end """ - vrna_bp_distance_pt(pt1, pt2) - - @brief Compute the "base pair" distance between two pair tables pt1 and pt2 of secondary structures. + vrna_ud_set_exp_prod_rule_cb(fc, pre_cb, exp_e_cb) - The pair tables should have the same length. - dist = number of base pairs in one structure but not in the other - same as edit distance with open-pair close-pair as move-set + @brief Attach production rule for partition function - @see vrna_bp_distance() + This function is the partition function companion of vrna_ud_set_prod_rule_cb(). - @param pt1 First structure in dot-bracket notation - @param pt2 Second structure in dot-bracket notation - @return The base pair distance between pt1 and pt2 -### Prototype -```c -int vrna_bp_distance_pt(const short *pt1, const short *pt2); -``` -""" -function vrna_bp_distance_pt(pt1, pt2) - ccall((:vrna_bp_distance_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}), pt1, pt2) -end + Use it to bind callbacks to (i) fill the @p U production rule dynamic programming + matrices and/or prepare the #vrna_unstructured_domain_s.data, and (ii) provide a callback + to retrieve partition functions for subsegments @f\$ [i,j] @f\$. -""" - vrna_bp_distance(str1, str2) + @image xml B_prod_rule.svg - @brief Compute the "base pair" distance between two secondary structures s1 and s2. + @image xml ligands_up_callback.svg - This is a wrapper around @b vrna_bp_distance_pt(). - The sequences should have the same length. - dist = number of base pairs in one structure but not in the other - same as edit distance with open-pair close-pair as move-set + @ingroup domains_up - @see vrna_bp_distance_pt() + @see vrna_ud_set_prod_rule_cb() - @param str1 First structure in dot-bracket notation - @param str2 Second structure in dot-bracket notation - @return The base pair distance between str1 and str2 + @param fc The #vrna_fold_compound_t data structure the callback will be bound to + @param pre_cb A pointer to a callback function for the @p B production rule + @param exp_e_cb A pointer to a callback function that retrieves the partition function + for a segment @f\$[i,j]@f\$ that may be bound by one or more ligands. ### Prototype ```c -int vrna_bp_distance(const char *str1, const char *str2); +void vrna_ud_set_exp_prod_rule_cb(vrna_fold_compound_t *fc, vrna_ud_exp_production_f pre_cb, vrna_ud_exp_f exp_e_cb); ``` """ -function vrna_bp_distance(str1, str2) - ccall((:vrna_bp_distance, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}), str1, str2) +function vrna_ud_set_exp_prod_rule_cb(fc, pre_cb, exp_e_cb) + ccall((:vrna_ud_set_exp_prod_rule_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_exp_production_f, vrna_ud_exp_f), fc, pre_cb, exp_e_cb) end """ - vrna_dist_mountain(str1, str2, p) + vrna_ud_set_prob_cb(fc, setter, getter) ### Prototype ```c -double vrna_dist_mountain(const char *str1, const char *str2, unsigned int p); +void vrna_ud_set_prob_cb(vrna_fold_compound_t *fc, vrna_ud_add_probs_f setter, vrna_ud_get_probs_f getter); ``` """ -function vrna_dist_mountain(str1, str2, p) - ccall((:vrna_dist_mountain, libRNA), Cdouble, (Ptr{Cchar}, Ptr{Cchar}, Cuint), str1, str2, p) +function vrna_ud_set_prob_cb(fc, setter, getter) + ccall((:vrna_ud_set_prob_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_add_probs_f, vrna_ud_get_probs_f), fc, setter, getter) end """ - vrna_refBPcnt_matrix(reference_pt, turn) - - @brief Make a reference base pair count matrix + pu_contrib - Get an upper triangular matrix containing the number of basepairs of a reference - structure for each interval [i,j] with iExpanded and HIT tree representations! + @f[ + = \\sum_{a,b} p_a p_b d(S_a,S_b) + @f] - @see vrna_db_to_tree_string(), #VRNA_STRUCTURE_TREE_EXPANDED, #VRNA_STRUCTURE_TREE_HIT, - @ref sec_structure_representations_tree + this can be computed from the pair probs @f\$ p_{ij} @f\$ as - @param tree A linear tree string representation of a secondary structure - @return A dot-bracket notation of the secondary structure provided in @p tree + @f[ + = \\sum_{ij} p_{ij}(1-p_{ij}) + @f] + + @param length The length of the sequence + @param pr The matrix containing the base pair probabilities + @return The mean pair distance of the structure ensemble ### Prototype ```c -char * vrna_tree_string_to_db(const char *tree); +double vrna_mean_bp_distance_pr(int length, FLT_OR_DBL *pr); ``` """ -function vrna_tree_string_to_db(tree) - ccall((:vrna_tree_string_to_db, libRNA), Ptr{Cchar}, (Ptr{Cchar},), tree) +function vrna_mean_bp_distance_pr(length, pr) + ccall((:vrna_mean_bp_distance_pr, libRNA), Cdouble, (Cint, Ptr{FLT_OR_DBL}), length, pr) end """ - assign_plist_from_db(pl, struc, pr) + vrna_mean_bp_distance(fc) + @brief Get the mean base pair distance in the thermodynamic ensemble -### Prototype -```c -; -``` -""" -function assign_plist_from_db(pl, struc, pr) - ccall((:assign_plist_from_db, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Ptr{Cchar}, Cfloat), pl, struc, pr) -end + @f[ + = \\sum_{a,b} p_a p_b d(S_a,S_b) + @f] -""" - pack_structure(struc) + this can be computed from the pair probs @f\$p_{ij}@f\$ as + @f[ + = \\sum_{ij} p_{ij}(1-p_{ij}) + @f] + @param fc The fold compound data structure + @return The mean pair distance of the structure ensemble ### Prototype ```c -; +double vrna_mean_bp_distance(vrna_fold_compound_t *fc); ``` """ -function pack_structure(struc) - ccall((:pack_structure, libRNA), Ptr{Cchar}, (Ptr{Cchar},), struc) +function vrna_mean_bp_distance(fc) + ccall((:vrna_mean_bp_distance, libRNA), Cdouble, (Ptr{vrna_fold_compound_t},), fc) end """ - unpack_structure(packed) + vrna_ensemble_defect_pt(fc, pt) + @brief Compute the Ensemble Defect for a given target structure provided as a @b vrna_ptable -### Prototype -```c -; -``` -""" -function unpack_structure(packed) - ccall((:unpack_structure, libRNA), Ptr{Cchar}, (Ptr{Cchar},), packed) -end + Given a target structure @f\$s@f\$, compute the average dissimilarity of a randomly + drawn structure from the ensemble, i.e.: -""" - make_pair_table(structure) + @f[ + ED(s) = 1 - \\frac{1}{n} \\sum_{ij, (i,j) \\in s} p_{ij} - \\frac{1}{n} \\sum_{i}(1 - s_i)q_i + @f] + + with sequence length @f\$n@f\$, the probability @f\$p_{ij}@f\$ of a base pair @f\$(i,j)@f\$, + the probability @f\$q_i = 1 - \\sum_j p_{ij}@f\$ of nucleotide @f\$i@f\$ being unpaired, and + the indicator variable @f\$s_i = 1@f\$ if @f\$\\exists (i,j) \\in s@f\$, and @f\$s_i = 0@f\$ otherwise. + + @pre The #vrna_fold_compound_t input parameter @p fc must contain a valid base pair + probability matrix. This means that partition function and base pair probabilities + must have been computed using @p fc before execution of this function! + @see vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect() + @param fc A fold_compound with pre-computed base pair probabilities + @param pt A pair table representing a target structure + @return The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met ### Prototype ```c -; +double vrna_ensemble_defect_pt(vrna_fold_compound_t *fc, const short *pt); ``` """ -function make_pair_table(structure) - ccall((:make_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function vrna_ensemble_defect_pt(fc, pt) + ccall((:vrna_ensemble_defect_pt, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}), fc, pt) end """ - make_pair_table_pk(structure) + vrna_ensemble_defect(fc, structure) + @brief Compute the Ensemble Defect for a given target structure -### Prototype -```c -; -``` -""" -function make_pair_table_pk(structure) - ccall((:make_pair_table_pk, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) -end + This is a wrapper around @b vrna_ensemble_defect_pt(). + Given a target structure @f\$s@f\$, compute the average dissimilarity of a randomly + drawn structure from the ensemble, i.e.: -""" - copy_pair_table(pt) + @f[ + ED(s) = 1 - \\frac{1}{n} \\sum_{ij, (i,j) \\in s} p_{ij} - \\frac{1}{n} \\sum_{i}(1 - s_i)q_i + @f] + + with sequence length @f\$n@f\$, the probability @f\$p_{ij}@f\$ of a base pair @f\$(i,j)@f\$, + the probability @f\$q_i = 1 - \\sum_j p_{ij}@f\$ of nucleotide @f\$i@f\$ being unpaired, and + the indicator variable @f\$s_i = 1@f\$ if @f\$\\exists (i,j) \\in s@f\$, and @f\$s_i = 0@f\$ otherwise. + + @pre The #vrna_fold_compound_t input parameter @p fc must contain a valid base pair + probability matrix. This means that partition function and base pair probabilities + must have been computed using @p fc before execution of this function! + @see vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect_pt() + @param fc A fold_compound with pre-computed base pair probabilities + @param structure A target structure in dot-bracket notation + @return The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met ### Prototype ```c -; +double vrna_ensemble_defect(vrna_fold_compound_t *fc, const char *structure); ``` """ -function copy_pair_table(pt) - ccall((:copy_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cshort},), pt) +function vrna_ensemble_defect(fc, structure) + ccall((:vrna_ensemble_defect, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - alimake_pair_table(structure) + vrna_positional_entropy(fc) + + @brief Compute a vector of positional entropies + + This function computes the positional entropies from base pair probabilities + as + + @f[ + S(i) = - \\sum_j p_{ij} \\log(p_{ij}) - q_i \\log(q_i) + @f] + + with unpaired probabilities @f\$ q_i = 1 - \\sum_j p_{ij} @f\$. + + Low entropy regions have little + structural flexibility and the reliability of the predicted structure is + high. High entropy implies many structural alternatives. While these + alternatives may be functionally important, they make structure prediction + more difficult and thus less reliable. + @pre This function requires pre-computed base pair probabilities! Thus, + vrna_pf() must be called beforehand. + @param fc A fold_compound with pre-computed base pair probabilities + @return A 1-based vector of positional entropies @f\$ S(i) @f\$. (position 0 contains the sequence length) ### Prototype ```c -; +double * vrna_positional_entropy(vrna_fold_compound_t *fc); ``` """ -function alimake_pair_table(structure) - ccall((:alimake_pair_table, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function vrna_positional_entropy(fc) + ccall((:vrna_positional_entropy, libRNA), Ptr{Cdouble}, (Ptr{vrna_fold_compound_t},), fc) end """ - make_pair_table_snoop(structure) + vrna_stack_prob(fc, cutoff) + + @brief Compute stacking probabilities + For each possible base pair @f\$(i,j)@f\$, compute the probability of a stack + @f\$(i,j)@f\$, @f\$(i+1, j-1)@f\$. + @param fc The fold compound data structure with precomputed base pair probabilities + @param cutoff A cutoff value that limits the output to stacks with @f\$ p > \\textrm{cutoff} @f\$. + @return A list of stacks with enclosing base pair @f\$(i,j)@f\$ and probabiltiy @f\$ p @f\$ ### Prototype ```c -; +vrna_ep_t * vrna_stack_prob(vrna_fold_compound_t *fc, double cutoff); ``` """ -function make_pair_table_snoop(structure) - ccall((:make_pair_table_snoop, libRNA), Ptr{Cshort}, (Ptr{Cchar},), structure) +function vrna_stack_prob(fc, cutoff) + ccall((:vrna_stack_prob, libRNA), Ptr{vrna_ep_t}, (Ptr{vrna_fold_compound_t}, Cdouble), fc, cutoff) end """ - make_loop_index_pt(pt) + vrna_pf_dimer_probs(FAB, FA, FB, prAB, prA, prB, Alength, exp_params) + @brief Compute Boltzmann probabilities of dimerization without homodimers -### Prototype -```c -; + Given the pair probabilities and free energies (in the null model) for a + dimer AB and the two constituent monomers A and B, compute the conditional pair + probabilities given that a dimer AB actually forms. + Null model pair probabilities are given as a list as produced by + vrna_plist_from_probs(), the dimer probabilities 'prAB' are modified in place. + + @param FAB free energy of dimer AB + @param FA free energy of monomer A + @param FB free energy of monomer B + @param prAB pair probabilities for dimer + @param prA pair probabilities monomer + @param prB pair probabilities monomer + @param Alength Length of molecule A + @param exp_params The precomputed Boltzmann factors +### Prototype +```c +void vrna_pf_dimer_probs(double FAB, double FA, double FB, vrna_ep_t *prAB, const vrna_ep_t *prA, const vrna_ep_t *prB, int Alength, const vrna_exp_param_t *exp_params); ``` """ -function make_loop_index_pt(pt) - ccall((:make_loop_index_pt, libRNA), Ptr{Cint}, (Ptr{Cshort},), pt) +function vrna_pf_dimer_probs(FAB, FA, FB, prAB, prA, prB, Alength, exp_params) + ccall((:vrna_pf_dimer_probs, libRNA), Cvoid, (Cdouble, Cdouble, Cdouble, Ptr{vrna_ep_t}, Ptr{vrna_ep_t}, Ptr{vrna_ep_t}, Cint, Ptr{vrna_exp_param_t}), FAB, FA, FB, prAB, prA, prB, Alength, exp_params) end """ - bp_distance(str1, str2) + vrna_pr_structure(fc, structure) + + @brief Compute the equilibrium probability of a particular secondary structure + + The probability @f\$p(s)@f\$ of a particular secondary structure @f\$s@f\$ can + be computed as + + @f[ + p(s) = \\frac{exp(-\\beta E(s)}{Z} + @f] + + from the structures free energy @f\$E(s)@f\$ and the partition function + + @f[ + Z = \\sum_s exp(-\\beta E(s)),\\quad\\mathrm{with}\\quad\\beta = \\frac{1}{RT} + @f] + + where @f\$R@f\$ is the gas constant and @f\$T@f\$ the thermodynamic temperature. + @pre The fold compound @p fc must have went through a call to vrna_pf() to + fill the dynamic programming matrices with the corresponding partition + function. + @param fc The fold compound data structure with precomputed partition function + @param structure The secondary structure to compute the probability for in dot-bracket notation + @return The probability of the input structure (range @f\$[0:1]@f\$) ### Prototype ```c -; +double vrna_pr_structure(vrna_fold_compound_t *fc, const char *structure); ``` """ -function bp_distance(str1, str2) - ccall((:bp_distance, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}), str1, str2) +function vrna_pr_structure(fc, structure) + ccall((:vrna_pr_structure, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - make_referenceBP_array(reference_pt, turn) + vrna_pr_energy(fc, e) ### Prototype ```c -; +double vrna_pr_energy(vrna_fold_compound_t *fc, double e); ``` """ -function make_referenceBP_array(reference_pt, turn) - ccall((:make_referenceBP_array, libRNA), Ptr{Cuint}, (Ptr{Cshort}, Cuint), reference_pt, turn) +function vrna_pr_energy(fc, e) + ccall((:vrna_pr_energy, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Cdouble), fc, e) end +mutable struct vrna_cstr_s end + +const vrna_cstr_t = Ptr{vrna_cstr_s} + """ - compute_BPdifferences(pt1, pt2, turn) + vrna_cstr(size, output) + + @brief Create a dynamic char * stream data structure + @see vrna_cstr_free(), vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr_discard(), vrna_cstr_printf() + @param size The initial size of the buffer in characters + @param output An optional output file stream handle that is used to write the collected data to (defaults to @em stdout if @em NULL) ### Prototype ```c -; +vrna_cstr_t vrna_cstr(size_t size, FILE *output); ``` """ -function compute_BPdifferences(pt1, pt2, turn) - ccall((:compute_BPdifferences, libRNA), Ptr{Cuint}, (Ptr{Cshort}, Ptr{Cshort}, Cuint), pt1, pt2, turn) +function vrna_cstr(size, output) + ccall((:vrna_cstr, libRNA), vrna_cstr_t, (Csize_t, Ptr{Libc.FILE}), size, output) end """ - assign_plist_from_pr(pl, probs, length, cutoff) + vrna_cstr_discard(buf) + @brief Discard the current content of the dynamic char * stream data structure + + @see vrna_cstr_free(), vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr_printf() + @param buf The dynamic char * stream data structure to free ### Prototype ```c -; +void vrna_cstr_discard(struct vrna_cstr_s *buf); ``` """ -function assign_plist_from_pr(pl, probs, length, cutoff) - ccall((:assign_plist_from_pr, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Ptr{FLT_OR_DBL}, Cint, Cdouble), pl, probs, length, cutoff) +function vrna_cstr_discard(buf) + ccall((:vrna_cstr_discard, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) end """ - parenthesis_structure(structure, bp, length) + vrna_cstr_free(buf) + + @brief Free the memory occupied by a dynamic char * stream data structure + + This function first flushes any remaining character data within the stream + and then free's the memory occupied by the data structure. + @see vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr() + @param buf The dynamic char * stream data structure to free ### Prototype ```c -; +void vrna_cstr_free(vrna_cstr_t buf); ``` """ -function parenthesis_structure(structure, bp, length) - ccall((:parenthesis_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) +function vrna_cstr_free(buf) + ccall((:vrna_cstr_free, libRNA), Cvoid, (vrna_cstr_t,), buf) end """ - parenthesis_zuker(structure, bp, length) + vrna_cstr_close(buf) + + @brief Free the memory occupied by a dynamic char * stream and close the output stream + + This function first flushes any remaining character data within the stream + then closes the attached output file stream (if any), and finally free's the + memory occupied by the data structure. + @see vrna_cstr_free(), vrna_cstr_fflush(), vrna_cstr() + @param buf The dynamic char * stream data structure to free ### Prototype ```c -; +void vrna_cstr_close(vrna_cstr_t buf); ``` """ -function parenthesis_zuker(structure, bp, length) - ccall((:parenthesis_zuker, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) +function vrna_cstr_close(buf) + ccall((:vrna_cstr_close, libRNA), Cvoid, (vrna_cstr_t,), buf) end """ - letter_structure(structure, bp, length) + vrna_cstr_fflush(buf) + + @brief Flush the dynamic char * output stream + + This function flushes the collected char * stream, either by writing + to the attached file handle, or simply by writing to @em stdout if + no file handle has been attached upon construction using vrna_cstr(). + + @post The stream buffer is empty after execution of this function + @see vrna_cstr(), vrna_cstr_close(), vrna_cstr_free() + @param buf The dynamic char * stream data structure to flush ### Prototype ```c -; +void vrna_cstr_fflush(struct vrna_cstr_s *buf); ``` """ -function letter_structure(structure, bp, length) - ccall((:letter_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{vrna_bp_stack_t}, Cint), structure, bp, length) +function vrna_cstr_fflush(buf) + ccall((:vrna_cstr_fflush, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) end """ - bppm_to_structure(structure, pr, length) + vrna_cstr_string(buf) ### Prototype ```c -; +const char * vrna_cstr_string(vrna_cstr_t buf); ``` """ -function bppm_to_structure(structure, pr, length) - ccall((:bppm_to_structure, libRNA), Cvoid, (Ptr{Cchar}, Ptr{FLT_OR_DBL}, Cuint), structure, pr, length) +function vrna_cstr_string(buf) + ccall((:vrna_cstr_string, libRNA), Ptr{Cchar}, (vrna_cstr_t,), buf) end """ - bppm_symbol(x) + vrna_cstr_print_fasta_header(buf, head) ### Prototype ```c -; +void vrna_cstr_print_fasta_header(vrna_cstr_t buf, const char *head); ``` """ -function bppm_symbol(x) - ccall((:bppm_symbol, libRNA), Cchar, (Ptr{Cfloat},), x) +function vrna_cstr_print_fasta_header(buf, head) + ccall((:vrna_cstr_print_fasta_header, libRNA), Cvoid, (vrna_cstr_t, Ptr{Cchar}), buf, head) end -# DEPRECATED -const vrna_callback_ud_energy = Cvoid +""" + vrna_cstr_print_eval_sd_corr(buf) -# DEPRECATED -const vrna_callback_ud_exp_energy = Cvoid -# DEPRECATED -const vrna_callback_ud_production = Cvoid +### Prototype +```c +void vrna_cstr_print_eval_sd_corr(struct vrna_cstr_s *buf); +``` +""" +function vrna_cstr_print_eval_sd_corr(buf) + ccall((:vrna_cstr_print_eval_sd_corr, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) +end -# DEPRECATED -const vrna_callback_ud_exp_production = Cvoid +""" + vrna_cstr_print_eval_ext_loop(buf, energy) -# DEPRECATED -const vrna_callback_ud_probs_add = Cvoid -# DEPRECATED -const vrna_callback_ud_probs_get = Cvoid +### Prototype +```c +void vrna_cstr_print_eval_ext_loop(struct vrna_cstr_s *buf, int energy); +``` +""" +function vrna_cstr_print_eval_ext_loop(buf, energy) + ccall((:vrna_cstr_print_eval_ext_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint), buf, energy) +end """ - vrna_ud_motifs_centroid(fc, structure) + vrna_cstr_print_eval_hp_loop(buf, i, j, si, sj, energy) - @brief Detect unstructured domains in centroid structure - Given a centroid structure and a set of unstructured domains compute - the list of unstructured domain motifs present in the centroid. - Since we do not explicitly annotate unstructured domain motifs in - dot-bracket strings, this function can be used to check for the - presence and location of unstructured domain motifs under the - assumption that the dot-bracket string is the centroid structure - of the equiibrium ensemble. +### Prototype +```c +void vrna_cstr_print_eval_hp_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); +``` +""" +function vrna_cstr_print_eval_hp_loop(buf, i, j, si, sj, energy) + ccall((:vrna_cstr_print_eval_hp_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) +end - @see vrna_centroid() +""" + vrna_cstr_print_eval_hp_loop_revert(buf, i, j, si, sj, energy) - @ingroup domains_up - @param fc The fold_compound data structure with pre-computed equilibrium probabilities and model settings - @param structure The centroid structure in dot-bracket notation - @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list with - @p start=0, @p number=-1 ### Prototype ```c -vrna_ud_motif_t * vrna_ud_motifs_centroid(vrna_fold_compound_t *fc, const char *structure); +void vrna_cstr_print_eval_hp_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); ``` """ -function vrna_ud_motifs_centroid(fc, structure) - ccall((:vrna_ud_motifs_centroid, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_cstr_print_eval_hp_loop_revert(buf, i, j, si, sj, energy) + ccall((:vrna_cstr_print_eval_hp_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) end """ - vrna_ud_motifs_MEA(fc, structure, probability_list) + vrna_cstr_print_eval_int_loop(buf, i, j, si, sj, k, l, sk, sl, energy) - @brief Detect unstructured domains in MEA structure - Given an MEA structure and a set of unstructured domains compute - the list of unstructured domain motifs present in the MEA structure. - Since we do not explicitly annotate unstructured domain motifs in - dot-bracket strings, this function can be used to check for the - presence and location of unstructured domain motifs under the - assumption that the dot-bracket string is the MEA structure - of the equiibrium ensemble. +### Prototype +```c +void vrna_cstr_print_eval_int_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int k, int l, char sk, char sl, int energy); +``` +""" +function vrna_cstr_print_eval_int_loop(buf, i, j, si, sj, k, l, sk, sl, energy) + ccall((:vrna_cstr_print_eval_int_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, k, l, sk, sl, energy) +end - @see MEA() +""" + vrna_cstr_print_eval_int_loop_revert(buf, i, j, si, sj, k, l, sk, sl, energy) - @ingroup domains_up - @param fc The fold_compound data structure with pre-computed equilibrium probabilities and model settings - @param structure The MEA structure in dot-bracket notation - @param probability_list The list of probabilities to extract the MEA structure from - @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list - with @p start=0, @p number=-1 ### Prototype ```c -vrna_ud_motif_t * vrna_ud_motifs_MEA(vrna_fold_compound_t *fc, const char *structure, vrna_ep_t *probability_list); +void vrna_cstr_print_eval_int_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int k, int l, char sk, char sl, int energy); ``` """ -function vrna_ud_motifs_MEA(fc, structure, probability_list) - ccall((:vrna_ud_motifs_MEA, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{vrna_ep_t}), fc, structure, probability_list) +function vrna_cstr_print_eval_int_loop_revert(buf, i, j, si, sj, k, l, sk, sl, energy) + ccall((:vrna_cstr_print_eval_int_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, k, l, sk, sl, energy) end """ - vrna_ud_motifs_MFE(fc, structure) + vrna_cstr_print_eval_mb_loop(buf, i, j, si, sj, energy) - @brief Detect unstructured domains in MFE structure - Given an MFE structure and a set of unstructured domains compute - the list of unstructured domain motifs present in the MFE structure. - Since we do not explicitly annotate unstructured domain motifs in - dot-bracket strings, this function can be used to check for the - presence and location of unstructured domain motifs under the - assumption that the dot-bracket string is the MFE structure - of the equiibrium ensemble. - - @see vrna_mfe() - - @ingroup domains_up - - @param fc The fold_compound data structure with model settings - @param structure The MFE structure in dot-bracket notation - @return A list of unstructured domain motifs (possibly NULL). The last element terminates the list with @p start=0, @p number=-1 ### Prototype ```c -vrna_ud_motif_t * vrna_ud_motifs_MFE(vrna_fold_compound_t *fc, const char *structure); +void vrna_cstr_print_eval_mb_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); ``` """ -function vrna_ud_motifs_MFE(fc, structure) - ccall((:vrna_ud_motifs_MFE, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_cstr_print_eval_mb_loop(buf, i, j, si, sj, energy) + ccall((:vrna_cstr_print_eval_mb_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) end """ - vrna_ud_add_motif(fc, motif, motif_en, motif_name, loop_type) - - @brief Add an unstructured domain motif, e.g. for ligand binding - - This function adds a ligand binding motif and the associated binding free energy - to the #vrna_ud_t attribute of a #vrna_fold_compound_t. The motif data - will then be used in subsequent secondary structure predictions. Multiple calls - to this function with different motifs append all additional data to a list of - ligands, which all will be evaluated. Ligand motif data can be removed from the - #vrna_fold_compound_t again using the vrna_ud_remove() function. The loop - type parameter allows one to limit the ligand binding to particular loop type, - such as the exterior loop, hairpin loops, interior loops, or multibranch loops. - - @see #VRNA_UNSTRUCTURED_DOMAIN_EXT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_HP_LOOP, - #VRNA_UNSTRUCTURED_DOMAIN_INT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_MB_LOOP, - #VRNA_UNSTRUCTURED_DOMAIN_ALL_LOOPS, vrna_ud_remove() - - @ingroup domains_up + vrna_cstr_print_eval_mb_loop_revert(buf, i, j, si, sj, energy) - @param fc The #vrna_fold_compound_t data structure the ligand motif should be bound to - @param motif The sequence motif the ligand binds to - @param motif_en The binding free energy of the ligand in kcal/mol - @param motif_name The name/id of the motif (may be @p NULL) - @param loop_type The loop type the ligand binds to ### Prototype ```c -void vrna_ud_add_motif(vrna_fold_compound_t *fc, const char *motif, double motif_en, const char *motif_name, unsigned int loop_type); +void vrna_cstr_print_eval_mb_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); ``` """ -function vrna_ud_add_motif(fc, motif, motif_en, motif_name, loop_type) - ccall((:vrna_ud_add_motif, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cdouble, Ptr{Cchar}, Cuint), fc, motif, motif_en, motif_name, loop_type) +function vrna_cstr_print_eval_mb_loop_revert(buf, i, j, si, sj, energy) + ccall((:vrna_cstr_print_eval_mb_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) end """ - vrna_ud_get_motif_size_at(fc, i, loop_type) + vrna_cstr_print_eval_gquad(buf, i, L, l, energy) - @brief Get a list of unique motif sizes that start at a certain position within the sequence ### Prototype ```c -int *vrna_ud_get_motif_size_at(vrna_fold_compound_t *fc, int i, unsigned int loop_type); +void vrna_cstr_print_eval_gquad(struct vrna_cstr_s *buf, int i, int L, int l[3], int energy); ``` """ -function vrna_ud_get_motif_size_at(fc, i, loop_type) - ccall((:vrna_ud_get_motif_size_at, libRNA), Ptr{Cint}, (Ptr{vrna_fold_compound_t}, Cint, Cuint), fc, i, loop_type) +function vrna_cstr_print_eval_gquad(buf, i, L, l, energy) + ccall((:vrna_cstr_print_eval_gquad, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Ptr{Cint}, Cint), buf, i, L, l, energy) end """ - vrna_ud_get_motifs_at(fc, i, loop_type) + vrna_move_s +@brief An atomic representation of the transition / move from one structure to its neighbor -### Prototype -```c -int * vrna_ud_get_motifs_at(vrna_fold_compound_t *fc, int i, unsigned int loop_type); -``` + An atomic transition / move may be one of the following: + - a base pair insertion, + - a base pair removal, or + - a base pair shift where an existing base pair changes one of its + pairing partner. + + These moves are encoded by two integer values that represent the affected 5' and 3' + nucleotide positions. Furthermore, we use the following convention on the signedness + of these encodings: + - both values are positive for insertion moves + - both values are negative for base pair removals + - both values have different signedness for shift moves, where the positive + value indicates the nucleotide that stays constant, and the others absolute value + is the new pairing partner + + @note A value of 0 in either field is used as list-end indicator and doesn't represent + any valid move. """ -function vrna_ud_get_motifs_at(fc, i, loop_type) - ccall((:vrna_ud_get_motifs_at, libRNA), Ptr{Cint}, (Ptr{vrna_fold_compound_t}, Cint, Cuint), fc, i, loop_type) +struct vrna_move_s + pos_5::Cint + pos_3::Cint + next::Ptr{Cvoid} # next::Ptr{vrna_move_t} +end + +function Base.getproperty(x::vrna_move_s, f::Symbol) + f === :next && return Ptr{vrna_move_t}(getfield(x, f)) + return getfield(x, f) end """ - vrna_ud_detect_motifs(fc, structure) + @brief A single move that transforms a secondary structure into one of its neighbors +""" +const vrna_move_t = vrna_move_s + +""" + vrna_move_init(pos_5, pos_3) + + @brief Create an atomic move + @see #vrna_move_s + @param pos_5 The 5' position of the move (positive for insertions, negative for removal, any value for shift moves) + @param pos_3 The 3' position of the move (positive for insertions, negative for removal, any value for shift moves) + @return An atomic move as specified by @p pos_5 and @p pos_3 ### Prototype ```c -vrna_ud_motif_t * vrna_ud_detect_motifs(vrna_fold_compound_t *fc, const char *structure); +vrna_move_t vrna_move_init(int pos_5, int pos_3); ``` """ -function vrna_ud_detect_motifs(fc, structure) - ccall((:vrna_ud_detect_motifs, libRNA), Ptr{vrna_ud_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_move_init(pos_5, pos_3) + ccall((:vrna_move_init, libRNA), vrna_move_t, (Cint, Cint), pos_5, pos_3) end """ - vrna_ud_remove(fc) - - @brief Remove ligand binding to unpaired stretches - - This function removes all ligand motifs that were bound to a #vrna_fold_compound_t using - the vrna_ud_add_motif() function. - - @ingroup domains_up + vrna_move_list_free(moves) - @param fc The #vrna_fold_compound_t data structure the ligand motif data should be removed from +delete all moves in a zero terminated list. ### Prototype ```c -void vrna_ud_remove(vrna_fold_compound_t *fc); +void vrna_move_list_free(vrna_move_t *moves); ``` """ -function vrna_ud_remove(fc) - ccall((:vrna_ud_remove, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_move_list_free(moves) + ccall((:vrna_move_list_free, libRNA), Cvoid, (Ptr{vrna_move_t},), moves) end """ - vrna_ud_set_data(fc, data, free_cb) - - @brief Attach an auxiliary data structure - - This function binds an arbitrary, auxiliary data structure for user-implemented ligand binding. - The optional callback @p free_cb will be passed the bound data structure whenever the #vrna_fold_compound_t - is removed from memory to avoid memory leaks. - - @see vrna_ud_set_prod_rule_cb(), vrna_ud_set_exp_prod_rule_cb(), - vrna_ud_remove() + vrna_move_apply(pt, m) - @ingroup domains_up +@brief Apply a particular move / transition to a secondary structure, i.e. transform a structure - @param fc The #vrna_fold_compound_t data structure the auxiliary data structure should be bound to - @param data A pointer to the auxiliary data structure - @param free_cb A pointer to a callback function that free's memory occupied by @p data +@param[in,out] pt The pair table representation of the secondary structure +@param[in] m The move to apply ### Prototype ```c -void vrna_ud_set_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f free_cb); +void vrna_move_apply(short *pt, const vrna_move_t *m); ``` """ -function vrna_ud_set_data(fc, data, free_cb) - ccall((:vrna_ud_set_data, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, free_cb) +function vrna_move_apply(pt, m) + ccall((:vrna_move_apply, libRNA), Cvoid, (Ptr{Cshort}, Ptr{vrna_move_t}), pt, m) end """ - vrna_ud_set_prod_rule_cb(fc, pre_cb, e_cb) - - @brief Attach production rule callbacks for free energies computations - - Use this function to bind a user-implemented grammar extension for unstructured - domains. - - The callback @p e_cb needs to evaluate the free energy contribution @f\$f(i,j)@f\$ of - the unpaired segment @f\$[i,j]@f\$. It will be executed in each of the regular secondary - structure production rules. Whenever the callback is passed the #VRNA_UNSTRUCTURED_DOMAIN_MOTIF - flag via its @p loop_type parameter the contribution of any ligand that consecutively - binds from position @f\$i@f\$ to @f\$j@f\$ (the white box) is requested. Otherwise, the callback - usually performs a lookup in the precomputed @p B matrices. Which @p B matrix is - addressed will be indicated by the flags #VRNA_UNSTRUCTURED_DOMAIN_EXT_LOOP, #VRNA_UNSTRUCTURED_DOMAIN_HP_LOOP - #VRNA_UNSTRUCTURED_DOMAIN_INT_LOOP, and #VRNA_UNSTRUCTURED_DOMAIN_MB_LOOP. As their names already imply, - they specify exterior loops (@p F production rule), hairpin loops and interior loops - (@p C production rule), and multibranch loops (@p M and @p M1 production rule). - - @image xml ligands_up_callback.svg - - The @p pre_cb callback will be executed as a pre-processing step right before the - regular secondary structure rules. Usually one would use this callback to fill the - dynamic programming matrices @p U and preparations of the auxiliary data structure - #vrna_unstructured_domain_s.data - - @image xml B_prod_rule.svg + vrna_move_apply_db(structure, pt, m) - @ingroup domains_up - @param fc The #vrna_fold_compound_t data structure the callback will be bound to - @param pre_cb A pointer to a callback function for the @p B production rule - @param e_cb A pointer to a callback function for free energy evaluation ### Prototype ```c -void vrna_ud_set_prod_rule_cb(vrna_fold_compound_t *fc, vrna_ud_production_f pre_cb, vrna_ud_f e_cb); +void vrna_move_apply_db(char *structure, const short *pt, const vrna_move_t *m); ``` """ -function vrna_ud_set_prod_rule_cb(fc, pre_cb, e_cb) - ccall((:vrna_ud_set_prod_rule_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_production_f, vrna_ud_f), fc, pre_cb, e_cb) +function vrna_move_apply_db(structure, pt, m) + ccall((:vrna_move_apply_db, libRNA), Cvoid, (Ptr{Cchar}, Ptr{Cshort}, Ptr{vrna_move_t}), structure, pt, m) end """ - vrna_ud_set_exp_prod_rule_cb(fc, pre_cb, exp_e_cb) - - @brief Attach production rule for partition function - - This function is the partition function companion of vrna_ud_set_prod_rule_cb(). - - Use it to bind callbacks to (i) fill the @p U production rule dynamic programming - matrices and/or prepare the #vrna_unstructured_domain_s.data, and (ii) provide a callback - to retrieve partition functions for subsegments @f\$ [i,j] @f\$. - - @image xml B_prod_rule.svg - - @image xml ligands_up_callback.svg - - @ingroup domains_up + vrna_move_is_removal(m) - @see vrna_ud_set_prod_rule_cb() + @brief Test whether a move is a base pair removal - @param fc The #vrna_fold_compound_t data structure the callback will be bound to - @param pre_cb A pointer to a callback function for the @p B production rule - @param exp_e_cb A pointer to a callback function that retrieves the partition function - for a segment @f\$[i,j]@f\$ that may be bound by one or more ligands. + @param m The move to test against + @return Non-zero if the move is a base pair removal, 0 otherwise ### Prototype ```c -void vrna_ud_set_exp_prod_rule_cb(vrna_fold_compound_t *fc, vrna_ud_exp_production_f pre_cb, vrna_ud_exp_f exp_e_cb); +int vrna_move_is_removal(const vrna_move_t *m); ``` """ -function vrna_ud_set_exp_prod_rule_cb(fc, pre_cb, exp_e_cb) - ccall((:vrna_ud_set_exp_prod_rule_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_exp_production_f, vrna_ud_exp_f), fc, pre_cb, exp_e_cb) +function vrna_move_is_removal(m) + ccall((:vrna_move_is_removal, libRNA), Cint, (Ptr{vrna_move_t},), m) end """ - vrna_ud_set_prob_cb(fc, setter, getter) + vrna_move_is_insertion(m) + @brief Test whether a move is a base pair insertion + @param m The move to test against + @return Non-zero if the move is a base pair insertion, 0 otherwise ### Prototype ```c -void vrna_ud_set_prob_cb(vrna_fold_compound_t *fc, vrna_ud_add_probs_f setter, vrna_ud_get_probs_f getter); +int vrna_move_is_insertion(const vrna_move_t *m); ``` """ -function vrna_ud_set_prob_cb(fc, setter, getter) - ccall((:vrna_ud_set_prob_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_ud_add_probs_f, vrna_ud_get_probs_f), fc, setter, getter) +function vrna_move_is_insertion(m) + ccall((:vrna_move_is_insertion, libRNA), Cint, (Ptr{vrna_move_t},), m) end """ - pu_contrib + vrna_move_is_shift(m) - @brief contributions to p_u + @brief Test whether a move is a base pair shift + + @param m The move to test against + @return Non-zero if the move is a base pair shift, 0 otherwise +### Prototype +```c +int vrna_move_is_shift(const vrna_move_t *m); +``` """ -struct pu_contrib - H::Ptr{Ptr{Cdouble}} - I::Ptr{Ptr{Cdouble}} - M::Ptr{Ptr{Cdouble}} - E::Ptr{Ptr{Cdouble}} - length::Cint - w::Cint +function vrna_move_is_shift(m) + ccall((:vrna_move_is_shift, libRNA), Cint, (Ptr{vrna_move_t},), m) end """ - interact + vrna_move_compare(m, b, pt) - @brief interaction data structure for RNAup -""" -struct interact - Pi::Ptr{Cdouble} - Gi::Ptr{Cdouble} - Gikjl::Cdouble - Gikjl_wo::Cdouble - i::Cint - k::Cint - j::Cint - l::Cint - length::Cint -end - -""" - pu_out + @brief Compare two moves - @brief Collection of all free_energy of beeing unpaired values for output -""" -struct pu_out - len::Cint - u_vals::Cint - contribs::Cint - header::Ptr{Ptr{Cchar}} - u_values::Ptr{Ptr{Cdouble}} -end + The function compares two moves @p m and @p b and returns + whether move @p m is lexicographically smaller (-1), larger (1) + or equal to move @p b. -""" - constrain + If any of the moves @p m or @p b is a shift move, this + comparison only makes sense in a structure context. Thus, + the third argument with the current structure must be provided. - @brief constraints for cofolding -""" -struct constrain - indx::Ptr{Cint} - ptype::Ptr{Cchar} -end + @note This function returns 0 (equality) upon any error, e.g. missing input -""" - duplexT + @warning Currently, shift moves are not supported! - @brief Data structure for RNAduplex + @param m The first move of the comparison + @param b The second move of the comparison + @param pt The pair table of the current structure that is compatible with both moves (maybe NULL if moves are guaranteed to be no shifts) + @return -1 if @p m < @p b, 1 if @p m > @p b, 0 otherwise +### Prototype +```c +int vrna_move_compare(const vrna_move_t *m, const vrna_move_t *b, const short *pt); +``` """ -struct duplexT - i::Cint - j::Cint - _end::Cint - structure::Ptr{Cchar} - energy::Cdouble - energy_backtrack::Cdouble - opening_backtrack_x::Cdouble - opening_backtrack_y::Cdouble - offset::Cint - dG1::Cdouble - dG2::Cdouble - ddG::Cdouble - tb::Cint - te::Cint - qb::Cint - qe::Cint +function vrna_move_compare(m, b, pt) + ccall((:vrna_move_compare, libRNA), Cint, (Ptr{vrna_move_t}, Ptr{vrna_move_t}, Ptr{Cshort}), m, b, pt) end """ - node + vrna_eval_structure(fc, structure) - @brief Data structure for RNAsnoop (fold energy list) -""" -struct node - k::Cint - energy::Cint - next::Ptr{node} -end + @brief Calculate the free energy of an already folded RNA -""" - @brief Data structure for RNAsnoop (fold energy list) -""" -const folden = node + This function allows for energy evaluation of a given pair of structure + and sequence (alignment). + Model details, energy parameters, and possibly soft constraints are used as provided + via the parameter 'fc'. The #vrna_fold_compound_t does not need to contain any DP matrices, + but requires all most basic init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode -""" - snoopT + @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE - @brief Data structure for RNAsnoop + @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), + vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_eval_covar_structure() + + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param structure Secondary structure in dot-bracket notation + @return The free energy of the input structure given the input sequence in kcal/mol +### Prototype +```c +float vrna_eval_structure(vrna_fold_compound_t *fc, const char *structure); +``` """ -struct snoopT - i::Cint - j::Cint - u::Cint - structure::Ptr{Cchar} - energy::Cfloat - Duplex_El::Cfloat - Duplex_Er::Cfloat - Loop_E::Cfloat - Loop_D::Cfloat - pscd::Cfloat - psct::Cfloat - pscg::Cfloat - Duplex_Ol::Cfloat - Duplex_Or::Cfloat - Duplex_Ot::Cfloat - fullStemEnergy::Cfloat +function vrna_eval_structure(fc, structure) + ccall((:vrna_eval_structure, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - dupVar + vrna_eval_covar_structure(fc, structure) - @brief Data structure used in RNApkplex -""" -struct dupVar - i::Cint - j::Cint - _end::Cint - pk_helix::Ptr{Cchar} - structure::Ptr{Cchar} - energy::Cdouble - offset::Cint - dG1::Cdouble - dG2::Cdouble - ddG::Cdouble - tb::Cint - te::Cint - qb::Cint - qe::Cint - inactive::Cint - processed::Cint -end + @brief Calculate the pseudo energy derived by the covariance scores of a set of aligned sequences -""" - vrna_pairing_probs(fc, structure) + Consensus structure prediction is driven by covariance scores of base pairs in rows of the + provided alignment. This function allows one to retrieve the total amount of this covariance pseudo + energy scores. + The #vrna_fold_compound_t does not need to contain any DP matrices, but requires all most basic + init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound_comparative(alignment, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode - @name Base pair probabilities and derived computations - @{ + @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_COMPARATIVE only! + + @see vrna_fold_compound_comparative(), vrna_eval_structure() + + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param structure Secondary (consensus) structure in dot-bracket notation + @return The covariance pseudo energy score of the input structure given the input sequence alignment in kcal/mol ### Prototype ```c -int vrna_pairing_probs(vrna_fold_compound_t *fc, char *structure); +float vrna_eval_covar_structure(vrna_fold_compound_t *fc, const char *structure); ``` """ -function vrna_pairing_probs(fc, structure) - ccall((:vrna_pairing_probs, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_eval_covar_structure(fc, structure) + ccall((:vrna_eval_covar_structure, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - vrna_mean_bp_distance_pr(length, pr) - - @brief Get the mean base pair distance in the thermodynamic ensemble from a probability matrix + vrna_eval_structure_verbose(fc, structure, file) - @f[ - = \\sum_{a,b} p_a p_b d(S_a,S_b) - @f] + @brief Calculate the free energy of an already folded RNA and print contributions on a per-loop base. - this can be computed from the pair probs @f\$ p_{ij} @f\$ as + This function is a simplyfied version of vrna_eval_structure_v() that uses the @em default + verbosity level. - @f[ - = \\sum_{ij} p_{ij}(1-p_{ij}) - @f] + @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - @param length The length of the sequence - @param pr The matrix containing the base pair probabilities - @return The mean pair distance of the structure ensemble + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param structure Secondary structure in dot-bracket notation + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -double vrna_mean_bp_distance_pr(int length, FLT_OR_DBL *pr); +float vrna_eval_structure_verbose(vrna_fold_compound_t *fc, const char *structure, FILE *file); ``` """ -function vrna_mean_bp_distance_pr(length, pr) - ccall((:vrna_mean_bp_distance_pr, libRNA), Cdouble, (Cint, Ptr{FLT_OR_DBL}), length, pr) +function vrna_eval_structure_verbose(fc, structure, file) + ccall((:vrna_eval_structure_verbose, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Libc.FILE}), fc, structure, file) end """ - vrna_mean_bp_distance(fc) + vrna_eval_structure_v(fc, structure, verbosity_level, file) - @brief Get the mean base pair distance in the thermodynamic ensemble + @brief Calculate the free energy of an already folded RNA and print contributions on a per-loop base. - @f[ - = \\sum_{a,b} p_a p_b d(S_a,S_b) - @f] + This function allows for detailed energy evaluation of a given sequence/structure pair. + In contrast to vrna_eval_structure() this function prints detailed energy contributions + based on individual loops to a file handle. If NULL is passed as file handle, this function + defaults to print to stdout. Any positive @p verbosity_level activates potential warning message + of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what + data is printed. A negative parameter @p verbosity_level turns off printing all together. - this can be computed from the pair probs @f\$p_{ij}@f\$ as + Model details, energy parameters, and possibly soft constraints are used as provided + via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, + but all the most basic init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode - @f[ - = \\sum_{ij} p_{ij}(1-p_{ij}) - @f] + @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - @param fc The fold compound data structure - @return The mean pair distance of the structure ensemble + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param structure Secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -double vrna_mean_bp_distance(vrna_fold_compound_t *fc); +float vrna_eval_structure_v(vrna_fold_compound_t *fc, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_mean_bp_distance(fc) - ccall((:vrna_mean_bp_distance, libRNA), Cdouble, (Ptr{vrna_fold_compound_t},), fc) +function vrna_eval_structure_v(fc, structure, verbosity_level, file) + ccall((:vrna_eval_structure_v, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), fc, structure, verbosity_level, file) end """ - vrna_ensemble_defect_pt(fc, pt) + vrna_eval_structure_cstr(fc, structure, verbosity_level, output_stream) - @brief Compute the Ensemble Defect for a given target structure provided as a @b vrna_ptable - Given a target structure @f\$s@f\$, compute the average dissimilarity of a randomly - drawn structure from the ensemble, i.e.: +### Prototype +```c +float vrna_eval_structure_cstr(vrna_fold_compound_t *fc, const char *structure, int verbosity_level, vrna_cstr_t output_stream); +``` +""" +function vrna_eval_structure_cstr(fc, structure, verbosity_level, output_stream) + ccall((:vrna_eval_structure_cstr, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, vrna_cstr_t), fc, structure, verbosity_level, output_stream) +end - @f[ - ED(s) = 1 - \\frac{1}{n} \\sum_{ij, (i,j) \\in s} p_{ij} - \\frac{1}{n} \\sum_{i}(1 - s_i)q_i - @f] +""" + vrna_eval_structure_pt(fc, pt) - with sequence length @f\$n@f\$, the probability @f\$p_{ij}@f\$ of a base pair @f\$(i,j)@f\$, - the probability @f\$q_i = 1 - \\sum_j p_{ij}@f\$ of nucleotide @f\$i@f\$ being unpaired, and - the indicator variable @f\$s_i = 1@f\$ if @f\$\\exists (i,j) \\in s@f\$, and @f\$s_i = 0@f\$ otherwise. + @brief Calculate the free energy of an already folded RNA - @pre The #vrna_fold_compound_t input parameter @p fc must contain a valid base pair - probability matrix. This means that partition function and base pair probabilities - must have been computed using @p fc before execution of this function! + This function allows for energy evaluation of a given sequence/structure pair where + the structure is provided in pair_table format as obtained from vrna_ptable(). + Model details, energy parameters, and possibly soft constraints are used as provided + via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, + but all the most basic init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode - @see vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect() + @see vrna_ptable(), vrna_eval_structure(), vrna_eval_structure_pt_verbose() - @param fc A fold_compound with pre-computed base pair probabilities - @param pt A pair table representing a target structure - @return The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param pt Secondary structure as pair_table + @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -double vrna_ensemble_defect_pt(vrna_fold_compound_t *fc, const short *pt); +int vrna_eval_structure_pt(vrna_fold_compound_t *fc, const short *pt); ``` """ -function vrna_ensemble_defect_pt(fc, pt) - ccall((:vrna_ensemble_defect_pt, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}), fc, pt) +function vrna_eval_structure_pt(fc, pt) + ccall((:vrna_eval_structure_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}), fc, pt) end """ - vrna_ensemble_defect(fc, structure) - - @brief Compute the Ensemble Defect for a given target structure - - This is a wrapper around @b vrna_ensemble_defect_pt(). - Given a target structure @f\$s@f\$, compute the average dissimilarity of a randomly - drawn structure from the ensemble, i.e.: - - @f[ - ED(s) = 1 - \\frac{1}{n} \\sum_{ij, (i,j) \\in s} p_{ij} - \\frac{1}{n} \\sum_{i}(1 - s_i)q_i - @f] + vrna_eval_structure_pt_verbose(fc, pt, file) - with sequence length @f\$n@f\$, the probability @f\$p_{ij}@f\$ of a base pair @f\$(i,j)@f\$, - the probability @f\$q_i = 1 - \\sum_j p_{ij}@f\$ of nucleotide @f\$i@f\$ being unpaired, and - the indicator variable @f\$s_i = 1@f\$ if @f\$\\exists (i,j) \\in s@f\$, and @f\$s_i = 0@f\$ otherwise. + @brief Calculate the free energy of an already folded RNA - @pre The #vrna_fold_compound_t input parameter @p fc must contain a valid base pair - probability matrix. This means that partition function and base pair probabilities - must have been computed using @p fc before execution of this function! + This function is a simplyfied version of vrna_eval_structure_simple_v() that uses the @em default + verbosity level. - @see vrna_pf(), vrna_pairing_probs(), vrna_ensemble_defect_pt() + @see vrna_eval_structure_pt_v(), vrna_ptable(), vrna_eval_structure_pt(), vrna_eval_structure_verbose() - @param fc A fold_compound with pre-computed base pair probabilities - @param structure A target structure in dot-bracket notation - @return The ensemble defect with respect to the target structure, or -1. upon failure, e.g. pre-conditions are not met + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param pt Secondary structure as pair_table + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -double vrna_ensemble_defect(vrna_fold_compound_t *fc, const char *structure); +int vrna_eval_structure_pt_verbose(vrna_fold_compound_t *fc, const short *pt, FILE *file); ``` """ -function vrna_ensemble_defect(fc, structure) - ccall((:vrna_ensemble_defect, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_eval_structure_pt_verbose(fc, pt, file) + ccall((:vrna_eval_structure_pt_verbose, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Ptr{Libc.FILE}), fc, pt, file) end """ - vrna_positional_entropy(fc) - - @brief Compute a vector of positional entropies - - This function computes the positional entropies from base pair probabilities - as - - @f[ - S(i) = - \\sum_j p_{ij} \\log(p_{ij}) - q_i \\log(q_i) - @f] + vrna_eval_structure_pt_v(fc, pt, verbosity_level, file) - with unpaired probabilities @f\$ q_i = 1 - \\sum_j p_{ij} @f\$. + @brief Calculate the free energy of an already folded RNA - Low entropy regions have little - structural flexibility and the reliability of the predicted structure is - high. High entropy implies many structural alternatives. While these - alternatives may be functionally important, they make structure prediction - more difficult and thus less reliable. + This function allows for energy evaluation of a given sequence/structure pair where + the structure is provided in pair_table format as obtained from vrna_ptable(). + Model details, energy parameters, and possibly soft constraints are used as provided + via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, + but all the most basic init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode + In contrast to vrna_eval_structure_pt() this function prints detailed energy contributions + based on individual loops to a file handle. If NULL is passed as file handle, this function + defaults to print to stdout. Any positive @p verbosity_level activates potential warning message + of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what + data is printed. A negative parameter @p verbosity_level turns off printing all together. - @pre This function requires pre-computed base pair probabilities! Thus, - vrna_pf() must be called beforehand. + @see vrna_ptable(), vrna_eval_structure_pt(), vrna_eval_structure_verbose() - @param fc A fold_compound with pre-computed base pair probabilities - @return A 1-based vector of positional entropies @f\$ S(i) @f\$. (position 0 contains the sequence length) + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param pt Secondary structure as pair_table + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -double * vrna_positional_entropy(vrna_fold_compound_t *fc); +int vrna_eval_structure_pt_v(vrna_fold_compound_t *fc, const short *pt, int verbosity_level, FILE *file); ``` """ -function vrna_positional_entropy(fc) - ccall((:vrna_positional_entropy, libRNA), Ptr{Cdouble}, (Ptr{vrna_fold_compound_t},), fc) +function vrna_eval_structure_pt_v(fc, pt, verbosity_level, file) + ccall((:vrna_eval_structure_pt_v, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), fc, pt, verbosity_level, file) end """ - vrna_stack_prob(fc, cutoff) + vrna_eval_structure_simple(string, structure) - @brief Compute stacking probabilities + @brief Calculate the free energy of an already folded RNA - For each possible base pair @f\$(i,j)@f\$, compute the probability of a stack - @f\$(i,j)@f\$, @f\$(i+1, j-1)@f\$. + This function allows for energy evaluation of a given sequence/structure pair. + In contrast to vrna_eval_structure() this function assumes default model details + and default energy parameters in order to evaluate the free energy of the secondary + structure. Therefore, it serves as a simple interface function for energy evaluation + for situations where no changes on the energy model are required. - @param fc The fold compound data structure with precomputed base pair probabilities - @param cutoff A cutoff value that limits the output to stacks with @f\$ p > \\textrm{cutoff} @f\$. - @return A list of stacks with enclosing base pair @f\$(i,j)@f\$ and probabiltiy @f\$ p @f\$ + @see vrna_eval_structure(), vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), + + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -vrna_ep_t * vrna_stack_prob(vrna_fold_compound_t *fc, double cutoff); +float vrna_eval_structure_simple(const char *string, const char *structure); ``` """ -function vrna_stack_prob(fc, cutoff) - ccall((:vrna_stack_prob, libRNA), Ptr{vrna_ep_t}, (Ptr{vrna_fold_compound_t}, Cdouble), fc, cutoff) +function vrna_eval_structure_simple(string, structure) + ccall((:vrna_eval_structure_simple, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end """ - vrna_pf_dimer_probs(FAB, FA, FB, prAB, prA, prB, Alength, exp_params) + vrna_eval_circ_structure(string, structure) - @brief Compute Boltzmann probabilities of dimerization without homodimers + @brief Evaluate the free energy of a sequence/structure pair where the sequence is circular - Given the pair probabilities and free energies (in the null model) for a - dimer AB and the two constituent monomers A and B, compute the conditional pair - probabilities given that a dimer AB actually forms. - Null model pair probabilities are given as a list as produced by - vrna_plist_from_probs(), the dimer probabilities 'prAB' are modified in place. + @see vrna_eval_structure_simple(), vrna_eval_gquad_structure(), vrna_eval_circ_consensus_structure(), + vrna_eval_circ_structure_v(), vrna_eval_structure() - @param FAB free energy of dimer AB - @param FA free energy of monomer A - @param FB free energy of monomer B - @param prAB pair probabilities for dimer - @param prA pair probabilities monomer - @param prB pair probabilities monomer - @param Alength Length of molecule A - @param exp_params The precomputed Boltzmann factors + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @return The free energy of the structure given the circular input sequence in kcal/mol ### Prototype ```c -void vrna_pf_dimer_probs(double FAB, double FA, double FB, vrna_ep_t *prAB, const vrna_ep_t *prA, const vrna_ep_t *prB, int Alength, const vrna_exp_param_t *exp_params); +float vrna_eval_circ_structure(const char *string, const char *structure); ``` """ -function vrna_pf_dimer_probs(FAB, FA, FB, prAB, prA, prB, Alength, exp_params) - ccall((:vrna_pf_dimer_probs, libRNA), Cvoid, (Cdouble, Cdouble, Cdouble, Ptr{vrna_ep_t}, Ptr{vrna_ep_t}, Ptr{vrna_ep_t}, Cint, Ptr{vrna_exp_param_t}), FAB, FA, FB, prAB, prA, prB, Alength, exp_params) +function vrna_eval_circ_structure(string, structure) + ccall((:vrna_eval_circ_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end """ - vrna_pr_structure(fc, structure) - - @brief Compute the equilibrium probability of a particular secondary structure - - The probability @f\$p(s)@f\$ of a particular secondary structure @f\$s@f\$ can - be computed as - - @f[ - p(s) = \\frac{exp(-\\beta E(s)}{Z} - @f] - - from the structures free energy @f\$E(s)@f\$ and the partition function + vrna_eval_gquad_structure(string, structure) - @f[ - Z = \\sum_s exp(-\\beta E(s)),\\quad\\mathrm{with}\\quad\\beta = \\frac{1}{RT} - @f] + @brief Evaluate the free energy of a sequence/structure pair where the structure may contain G-Quadruplexes - where @f\$R@f\$ is the gas constant and @f\$T@f\$ the thermodynamic temperature. + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode - @pre The fold compound @p fc must have went through a call to vrna_pf() to - fill the dynamic programming matrices with the corresponding partition - function. + @see vrna_eval_structure_simple(), vrna_eval_circ_structure(), vrna_eval_gquad_consensus_structure(), + vrna_eval_gquad_structure_v(), vrna_eval_structure() - @param fc The fold compound data structure with precomputed partition function - @param structure The secondary structure to compute the probability for in dot-bracket notation - @return The probability of the input structure (range @f\$[0:1]@f\$) + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @return The free energy of the structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -double vrna_pr_structure(vrna_fold_compound_t *fc, const char *structure); +float vrna_eval_gquad_structure(const char *string, const char *structure); ``` """ -function vrna_pr_structure(fc, structure) - ccall((:vrna_pr_structure, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_eval_gquad_structure(string, structure) + ccall((:vrna_eval_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end """ - vrna_pr_energy(fc, e) + vrna_eval_circ_gquad_structure(string, structure) + @brief Evaluate the free energy of a sequence/structure pair where the sequence is circular and + the structure may contain G-Quadruplexes + + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode + + @see vrna_eval_structure_simple(), vrna_eval_circ_gquad_consensus_structure(), + vrna_eval_circ_gquad_structure_v(), vrna_eval_structure() + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @return The free energy of the structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -double vrna_pr_energy(vrna_fold_compound_t *fc, double e); +float vrna_eval_circ_gquad_structure(const char *string, const char *structure); ``` """ -function vrna_pr_energy(fc, e) - ccall((:vrna_pr_energy, libRNA), Cdouble, (Ptr{vrna_fold_compound_t}, Cdouble), fc, e) +function vrna_eval_circ_gquad_structure(string, structure) + ccall((:vrna_eval_circ_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end -mutable struct vrna_cstr_s end - -const vrna_cstr_t = Ptr{vrna_cstr_s} - """ - vrna_cstr(size, output) + vrna_eval_structure_simple_verbose(string, structure, file) - @brief Create a dynamic char * stream data structure + @brief Calculate the free energy of an already folded RNA and print contributions per loop. - @see vrna_cstr_free(), vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr_discard(), vrna_cstr_printf() + This function is a simplyfied version of vrna_eval_structure_simple_v() that uses the @em default + verbosity level. - @param size The initial size of the buffer in characters - @param output An optional output file stream handle that is used to write the collected data to (defaults to @em stdout if @em NULL) + @see vrna_eval_structure_simple_v(), vrna_eval_structure_verbose(), vrna_eval_structure_pt(), + vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose() + + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -vrna_cstr_t vrna_cstr(size_t size, FILE *output); +float vrna_eval_structure_simple_verbose(const char *string, const char *structure, FILE *file); ``` """ -function vrna_cstr(size, output) - ccall((:vrna_cstr, libRNA), vrna_cstr_t, (Csize_t, Ptr{Libc.FILE}), size, output) +function vrna_eval_structure_simple_verbose(string, structure, file) + ccall((:vrna_eval_structure_simple_verbose, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Libc.FILE}), string, structure, file) end """ - vrna_cstr_discard(buf) + vrna_eval_structure_simple_v(string, structure, verbosity_level, file) - @brief Discard the current content of the dynamic char * stream data structure + @brief Calculate the free energy of an already folded RNA and print contributions per loop. - @see vrna_cstr_free(), vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr_printf() + This function allows for detailed energy evaluation of a given sequence/structure pair. + In contrast to vrna_eval_structure() this function prints detailed energy contributions + based on individual loops to a file handle. If NULL is passed as file handle, this function + defaults to print to stdout. Any positive @p verbosity_level activates potential warning message + of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what + data is printed. A negative parameter @p verbosity_level turns off printing all together. - @param buf The dynamic char * stream data structure to free + In contrast to vrna_eval_structure_verbose() this function assumes default model details + and default energy parameters in order to evaluate the free energy of the secondary + structure. Threefore, it serves as a simple interface function for energy evaluation + for situations where no changes on the energy model are required. + + @see vrna_eval_structure_verbose(), vrna_eval_structure_pt(), vrna_eval_structure_pt_verbose(), + + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -void vrna_cstr_discard(struct vrna_cstr_s *buf); +float vrna_eval_structure_simple_v(const char *string, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_discard(buf) - ccall((:vrna_cstr_discard, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) +function vrna_eval_structure_simple_v(string, structure, verbosity_level, file) + ccall((:vrna_eval_structure_simple_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) end """ - vrna_cstr_free(buf) + vrna_eval_circ_structure_v(string, structure, verbosity_level, file) - @brief Free the memory occupied by a dynamic char * stream data structure + @brief Evaluate free energy of a sequence/structure pair, assume sequence to be circular and + print contributions per loop - This function first flushes any remaining character data within the stream - and then free's the memory occupied by the data structure. + This function is the same as vrna_eval_structure_simple_v() but assumes the input sequence + to be circularized. - @see vrna_cstr_close(), vrna_cstr_fflush(), vrna_cstr() + @see vrna_eval_structure_simple_v(), vrna_eval_circ_structure(), vrna_eval_structure_verbose() - @param buf The dynamic char * stream data structure to free + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -void vrna_cstr_free(vrna_cstr_t buf); +float vrna_eval_circ_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_free(buf) - ccall((:vrna_cstr_free, libRNA), Cvoid, (vrna_cstr_t,), buf) +function vrna_eval_circ_structure_v(string, structure, verbosity_level, file) + ccall((:vrna_eval_circ_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) end """ - vrna_cstr_close(buf) + vrna_eval_gquad_structure_v(string, structure, verbosity_level, file) - @brief Free the memory occupied by a dynamic char * stream and close the output stream + @brief Evaluate free energy of a sequence/structure pair, allow for G-Quadruplexes in the structure + and print contributions per loop - This function first flushes any remaining character data within the stream - then closes the attached output file stream (if any), and finally free's the - memory occupied by the data structure. + This function is the same as vrna_eval_structure_simple_v() but allows for annotated G-Quadruplexes + in the dot-bracket structure input. - @see vrna_cstr_free(), vrna_cstr_fflush(), vrna_cstr() + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode - @param buf The dynamic char * stream data structure to free + @see vrna_eval_structure_simple_v(), vrna_eval_gquad_structure(), vrna_eval_structure_verbose() + + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -void vrna_cstr_close(vrna_cstr_t buf); +float vrna_eval_gquad_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_close(buf) - ccall((:vrna_cstr_close, libRNA), Cvoid, (vrna_cstr_t,), buf) +function vrna_eval_gquad_structure_v(string, structure, verbosity_level, file) + ccall((:vrna_eval_gquad_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) end """ - vrna_cstr_fflush(buf) - - @brief Flush the dynamic char * output stream + vrna_eval_circ_gquad_structure_v(string, structure, verbosity_level, file) - This function flushes the collected char * stream, either by writing - to the attached file handle, or simply by writing to @em stdout if - no file handle has been attached upon construction using vrna_cstr(). + @brief Evaluate free energy of a sequence/structure pair, assume sequence to be circular, allow + for G-Quadruplexes in the structure, and print contributions per loop - @post The stream buffer is empty after execution of this function + This function is the same as vrna_eval_structure_simple_v() but assumes the input sequence to + be circular and allows for annotated G-Quadruplexes in the dot-bracket structure input. - @see vrna_cstr(), vrna_cstr_close(), vrna_cstr_free() + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode - @param buf The dynamic char * stream data structure to flush + @param string RNA sequence in uppercase letters + @param structure Secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -void vrna_cstr_fflush(struct vrna_cstr_s *buf); +float vrna_eval_circ_gquad_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_fflush(buf) - ccall((:vrna_cstr_fflush, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) +function vrna_eval_circ_gquad_structure_v(string, structure, verbosity_level, file) + ccall((:vrna_eval_circ_gquad_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) end """ - vrna_cstr_string(buf) + vrna_eval_consensus_structure_simple(alignment, structure) + @brief Calculate the free energy of an already folded RNA sequence alignment -### Prototype -```c -const char * vrna_cstr_string(vrna_cstr_t buf); -``` -""" -function vrna_cstr_string(buf) - ccall((:vrna_cstr_string, libRNA), Ptr{Cchar}, (vrna_cstr_t,), buf) -end + This function allows for energy evaluation for a given multiple sequence alignment + and consensus structure pair. + In contrast to vrna_eval_structure() this function assumes default model details + and default energy parameters in order to evaluate the free energy of the secondary + structure. Therefore, it serves as a simple interface function for energy evaluation + for situations where no changes on the energy model are required. -""" - vrna_cstr_print_fasta_header(buf, head) + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_covar_structure(), vrna_eval_structure(), vrna_eval_structure_pt(), + vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose() + @param alignment RNA sequence alignment in uppercase letters and hyphen ('-') to denote gaps + @param structure Consensus Secondary structure in dot-bracket notation + @return The free energy of the consensus structure given the input alignment in kcal/mol ### Prototype ```c -void vrna_cstr_print_fasta_header(vrna_cstr_t buf, const char *head); +float vrna_eval_consensus_structure_simple(const char **alignment, const char *structure); ``` """ -function vrna_cstr_print_fasta_header(buf, head) - ccall((:vrna_cstr_print_fasta_header, libRNA), Cvoid, (vrna_cstr_t, Ptr{Cchar}), buf, head) +function vrna_eval_consensus_structure_simple(alignment, structure) + ccall((:vrna_eval_consensus_structure_simple, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) end """ - vrna_cstr_print_eval_sd_corr(buf) + vrna_eval_circ_consensus_structure(alignment, structure) + + @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair + where the sequences are circular + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + + @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_gquad_consensus_structure(), + vrna_eval_circ_structure(), vrna_eval_circ_consensus_structure_v(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters + @param structure Consensus secondary structure in dot-bracket notation + @return The free energy of the consensus structure given the circular input sequence in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_sd_corr(struct vrna_cstr_s *buf); +float vrna_eval_circ_consensus_structure(const char **alignment, const char *structure); ``` """ -function vrna_cstr_print_eval_sd_corr(buf) - ccall((:vrna_cstr_print_eval_sd_corr, libRNA), Cvoid, (Ptr{vrna_cstr_s},), buf) +function vrna_eval_circ_consensus_structure(alignment, structure) + ccall((:vrna_eval_circ_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) end """ - vrna_cstr_print_eval_ext_loop(buf, energy) + vrna_eval_gquad_consensus_structure(alignment, structure) + @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair + where the structure may contain G-Quadruplexes -### Prototype -```c -void vrna_cstr_print_eval_ext_loop(struct vrna_cstr_s *buf, int energy); -``` -""" -function vrna_cstr_print_eval_ext_loop(buf, energy) - ccall((:vrna_cstr_print_eval_ext_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint), buf, energy) -end + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode -""" - vrna_cstr_print_eval_hp_loop(buf, i, j, si, sj, energy) + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_circ_consensus_structure(), + vrna_eval_gquad_structure(), vrna_eval_gquad_consensus_structure_v(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters + @param structure Consensus secondary structure in dot-bracket notation + @return The free energy of the consensus structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_hp_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); +float vrna_eval_gquad_consensus_structure(const char **alignment, const char *structure); ``` """ -function vrna_cstr_print_eval_hp_loop(buf, i, j, si, sj, energy) - ccall((:vrna_cstr_print_eval_hp_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) +function vrna_eval_gquad_consensus_structure(alignment, structure) + ccall((:vrna_eval_gquad_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) end """ - vrna_cstr_print_eval_hp_loop_revert(buf, i, j, si, sj, energy) + vrna_eval_circ_gquad_consensus_structure(alignment, structure) + + @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair + where the sequence is circular and the structure may contain G-Quadruplexes + + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode + + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_circ_consensus_structure(), + vrna_eval_gquad_structure(), vrna_eval_circ_gquad_consensus_structure_v(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters + @param structure Consensus secondary structure in dot-bracket notation + @return The free energy of the consensus structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_hp_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); +float vrna_eval_circ_gquad_consensus_structure(const char **alignment, const char *structure); ``` """ -function vrna_cstr_print_eval_hp_loop_revert(buf, i, j, si, sj, energy) - ccall((:vrna_cstr_print_eval_hp_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) +function vrna_eval_circ_gquad_consensus_structure(alignment, structure) + ccall((:vrna_eval_circ_gquad_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) end """ - vrna_cstr_print_eval_int_loop(buf, i, j, si, sj, k, l, sk, sl, energy) + vrna_eval_consensus_structure_simple_verbose(alignment, structure, file) + + @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment and print + contributions per loop. + + This function is a simplyfied version of vrna_eval_consensus_structure_simple_v() that uses the + @em default verbosity level. + + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_consensus_structure_simple_v(), vrna_eval_structure_verbose(), vrna_eval_structure_pt(), + vrna_eval_structure_pt_verbose() + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param structure Consensus secondary structure in dot-bracket notation + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the conensus structure given the aligned input sequences in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_int_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int k, int l, char sk, char sl, int energy); +float vrna_eval_consensus_structure_simple_verbose(const char **alignment, const char *structure, FILE *file); ``` """ -function vrna_cstr_print_eval_int_loop(buf, i, j, si, sj, k, l, sk, sl, energy) - ccall((:vrna_cstr_print_eval_int_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, k, l, sk, sl, energy) +function vrna_eval_consensus_structure_simple_verbose(alignment, structure, file) + ccall((:vrna_eval_consensus_structure_simple_verbose, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Libc.FILE}), alignment, structure, file) end """ - vrna_cstr_print_eval_int_loop_revert(buf, i, j, si, sj, k, l, sk, sl, energy) + vrna_eval_consensus_structure_simple_v(alignment, structure, verbosity_level, file) + @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment and print + contributions per loop. + This function allows for detailed energy evaluation of a given sequence alignment/consensus + structure pair. In contrast to vrna_eval_consensus_structure_simple() this function prints + detailed energy contributions based on individual loops to a file handle. If NULL is passed + as file handle, this function defaults to print to stdout. Any positive @p verbosity_level + activates potential warning message of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ + allow for detailed control of what data is printed. A negative parameter @p verbosity_level + turns off printing all together. + + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + + @see vrna_eval_consensus_structure(), vrna_eval_structure() + + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param structure Consensus secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the consensus structure given the sequence alignment in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_int_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int k, int l, char sk, char sl, int energy); +float vrna_eval_consensus_structure_simple_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_print_eval_int_loop_revert(buf, i, j, si, sj, k, l, sk, sl, energy) - ccall((:vrna_cstr_print_eval_int_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, k, l, sk, sl, energy) +function vrna_eval_consensus_structure_simple_v(alignment, structure, verbosity_level, file) + ccall((:vrna_eval_consensus_structure_simple_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) end """ - vrna_cstr_print_eval_mb_loop(buf, i, j, si, sj, energy) + vrna_eval_circ_consensus_structure_v(alignment, structure, verbosity_level, file) + + @brief Evaluate the free energy of a consensus structure for an alignment of circular RNA sequences + and print contributions per loop. + + This function is identical with vrna_eval_consensus_structure_simple_v() but assumed the + aligned sequences to be circular. + + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_consensus_structure_simple_v(), vrna_eval_circ_consensus_structure(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param structure Consensus secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the consensus structure given the sequence alignment in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_mb_loop(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); +float vrna_eval_circ_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_print_eval_mb_loop(buf, i, j, si, sj, energy) - ccall((:vrna_cstr_print_eval_mb_loop, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) +function vrna_eval_circ_consensus_structure_v(alignment, structure, verbosity_level, file) + ccall((:vrna_eval_circ_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) end """ - vrna_cstr_print_eval_mb_loop_revert(buf, i, j, si, sj, energy) + vrna_eval_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) + + @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment, allow for + annotated G-Quadruplexes in the structure and print contributions per loop. + + This function is identical with vrna_eval_consensus_structure_simple_v() but allows for annotated + G-Quadruplexes in the consensus structure. + + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + + @see vrna_eval_consensus_structure_simple_v(), vrna_eval_gquad_consensus_structure(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param structure Consensus secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the consensus structure given the sequence alignment in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_mb_loop_revert(struct vrna_cstr_s *buf, int i, int j, char si, char sj, int energy); +float vrna_eval_gquad_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_print_eval_mb_loop_revert(buf, i, j, si, sj, energy) - ccall((:vrna_cstr_print_eval_mb_loop_revert, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Cchar, Cchar, Cint), buf, i, j, si, sj, energy) +function vrna_eval_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) + ccall((:vrna_eval_gquad_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) end """ - vrna_cstr_print_eval_gquad(buf, i, L, l, energy) + vrna_eval_circ_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) + + @brief Evaluate the free energy of a consensus structure for an alignment of circular RNA sequences, + allow for annotated G-Quadruplexes in the structure and print contributions per loop. + + This function is identical with vrna_eval_consensus_structure_simple_v() but assumes the sequences in + the alignment to be circular and allows for annotated G-Quadruplexes in the consensus structure. + + G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must + be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: + @code{.unparsed} + GGAAGGAAAGGAGG + ++..++...++.++ + @endcode + + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + @see vrna_eval_consensus_structure_simple_v(), vrna_eval_circ_gquad_consensus_structure(), vrna_eval_structure() + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param structure Consensus secondary structure in dot-bracket notation + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the consensus structure given the sequence alignment in kcal/mol ### Prototype ```c -void vrna_cstr_print_eval_gquad(struct vrna_cstr_s *buf, int i, int L, int l[3], int energy); +float vrna_eval_circ_gquad_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); ``` """ -function vrna_cstr_print_eval_gquad(buf, i, L, l, energy) - ccall((:vrna_cstr_print_eval_gquad, libRNA), Cvoid, (Ptr{vrna_cstr_s}, Cint, Cint, Ptr{Cint}, Cint), buf, i, L, l, energy) +function vrna_eval_circ_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) + ccall((:vrna_eval_circ_gquad_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) end """ - vrna_move_s + vrna_eval_structure_pt_simple(string, pt) -@brief An atomic representation of the transition / move from one structure to its neighbor + @brief Calculate the free energy of an already folded RNA - An atomic transition / move may be one of the following: - - a base pair insertion, - - a base pair removal, or - - a base pair shift where an existing base pair changes one of its - pairing partner. + In contrast to vrna_eval_structure_pt() this function assumes default model details + and default energy parameters in order to evaluate the free energy of the secondary + structure. Threefore, it serves as a simple interface function for energy evaluation + for situations where no changes on the energy model are required. - These moves are encoded by two integer values that represent the affected 5' and 3' - nucleotide positions. Furthermore, we use the following convention on the signedness - of these encodings: - - both values are positive for insertion moves - - both values are negative for base pair removals - - both values have different signedness for shift moves, where the positive - value indicates the nucleotide that stays constant, and the others absolute value - is the new pairing partner + @see vrna_ptable(), vrna_eval_structure_simple(), vrna_eval_structure_pt() - @note A value of 0 in either field is used as list-end indicator and doesn't represent - any valid move. + @param string RNA sequence in uppercase letters + @param pt Secondary structure as pair_table + @return The free energy of the input structure given the input sequence in 10cal/mol +### Prototype +```c +int vrna_eval_structure_pt_simple(const char *string, const short *pt); +``` """ -struct vrna_move_s - pos_5::Cint - pos_3::Cint - next::Ptr{Cvoid} # next::Ptr{vrna_move_t} -end - -function Base.getproperty(x::vrna_move_s, f::Symbol) - f === :next && return Ptr{vrna_move_t}(getfield(x, f)) - return getfield(x, f) +function vrna_eval_structure_pt_simple(string, pt) + ccall((:vrna_eval_structure_pt_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}), string, pt) end """ - @brief A single move that transforms a secondary structure into one of its neighbors -""" -const vrna_move_t = vrna_move_s + vrna_eval_structure_pt_simple_verbose(string, pt, file) -""" - vrna_move_init(pos_5, pos_3) + @brief Calculate the free energy of an already folded RNA - @brief Create an atomic move + This function is a simplyfied version of vrna_eval_structure_pt_simple_v() that uses the @em default + verbosity level. - @see #vrna_move_s + @see vrna_eval_structure_pt_simple_v(), vrna_ptable(), vrna_eval_structure_pt_verbose(), vrna_eval_structure_simple() - @param pos_5 The 5' position of the move (positive for insertions, negative for removal, any value for shift moves) - @param pos_3 The 3' position of the move (positive for insertions, negative for removal, any value for shift moves) - @return An atomic move as specified by @p pos_5 and @p pos_3 + @param string RNA sequence in uppercase letters + @param pt Secondary structure as pair_table + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -vrna_move_t vrna_move_init(int pos_5, int pos_3); +int vrna_eval_structure_pt_simple_verbose(const char *string, const short *pt, FILE *file); ``` """ -function vrna_move_init(pos_5, pos_3) - ccall((:vrna_move_init, libRNA), vrna_move_t, (Cint, Cint), pos_5, pos_3) +function vrna_eval_structure_pt_simple_verbose(string, pt, file) + ccall((:vrna_eval_structure_pt_simple_verbose, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Libc.FILE}), string, pt, file) end """ - vrna_move_list_free(moves) + vrna_eval_structure_pt_simple_v(string, pt, verbosity_level, file) -delete all moves in a zero terminated list. + @brief Calculate the free energy of an already folded RNA + + This function allows for energy evaluation of a given sequence/structure pair where + the structure is provided in pair_table format as obtained from vrna_ptable(). + Model details, energy parameters, and possibly soft constraints are used as provided + via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, + but all the most basic init values as one would get from a call like this: + @code{.c} +fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); + @endcode + In contrast to vrna_eval_structure_pt_verbose() this function assumes default model details + and default energy parameters in order to evaluate the free energy of the secondary + structure. Threefore, it serves as a simple interface function for energy evaluation + for situations where no changes on the energy model are required. + + @see vrna_ptable(), vrna_eval_structure_pt_v(), vrna_eval_structure_simple() + + @param string RNA sequence in uppercase letters + @param pt Secondary structure as pair_table + @param verbosity_level The level of verbosity of this function + @param file A file handle where this function should print to (may be NULL). + @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -void vrna_move_list_free(vrna_move_t *moves); +int vrna_eval_structure_pt_simple_v(const char *string, const short *pt, int verbosity_level, FILE *file); ``` """ -function vrna_move_list_free(moves) - ccall((:vrna_move_list_free, libRNA), Cvoid, (Ptr{vrna_move_t},), moves) +function vrna_eval_structure_pt_simple_v(string, pt, verbosity_level, file) + ccall((:vrna_eval_structure_pt_simple_v, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), string, pt, verbosity_level, file) end """ - vrna_move_apply(pt, m) + vrna_eval_consensus_structure_pt_simple(alignment, pt) -@brief Apply a particular move / transition to a secondary structure, i.e. transform a structure + @brief Evaluate the Free Energy of a Consensus Secondary Structure given a Sequence Alignment -@param[in,out] pt The pair table representation of the secondary structure -@param[in] m The move to apply + @note The free energy returned from this function already includes the covariation + pseudo energies that is used fir comparative structure prediction within this + library. + + @see vrna_eval_consensus_structure_simple(), vrna_eval_structure_pt(), vrna_eval_structure(), + vrna_eval_covar_structure() + + @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') + @param pt Secondary structure in pair table format + @return Free energy of the consensus structure in 10cal/mol ### Prototype ```c -void vrna_move_apply(short *pt, const vrna_move_t *m); +int vrna_eval_consensus_structure_pt_simple(const char **alignment, const short *pt); ``` """ -function vrna_move_apply(pt, m) - ccall((:vrna_move_apply, libRNA), Cvoid, (Ptr{Cshort}, Ptr{vrna_move_t}), pt, m) +function vrna_eval_consensus_structure_pt_simple(alignment, pt) + ccall((:vrna_eval_consensus_structure_pt_simple, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}), alignment, pt) end """ - vrna_move_apply_db(structure, pt, m) + vrna_eval_consensus_structure_pt_simple_verbose(alignment, pt, file) ### Prototype ```c -void vrna_move_apply_db(char *structure, const short *pt, const vrna_move_t *m); +int vrna_eval_consensus_structure_pt_simple_verbose(const char **alignment, const short *pt, FILE *file); ``` """ -function vrna_move_apply_db(structure, pt, m) - ccall((:vrna_move_apply_db, libRNA), Cvoid, (Ptr{Cchar}, Ptr{Cshort}, Ptr{vrna_move_t}), structure, pt, m) +function vrna_eval_consensus_structure_pt_simple_verbose(alignment, pt, file) + ccall((:vrna_eval_consensus_structure_pt_simple_verbose, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}, Ptr{Libc.FILE}), alignment, pt, file) end """ - vrna_move_is_removal(m) + vrna_eval_consensus_structure_pt_simple_v(alignment, pt, verbosity_level, file) - @brief Test whether a move is a base pair removal - @param m The move to test against - @return Non-zero if the move is a base pair removal, 0 otherwise ### Prototype ```c -int vrna_move_is_removal(const vrna_move_t *m); +int vrna_eval_consensus_structure_pt_simple_v(const char **alignment, const short *pt, int verbosity_level, FILE *file); ``` """ -function vrna_move_is_removal(m) - ccall((:vrna_move_is_removal, libRNA), Cint, (Ptr{vrna_move_t},), m) +function vrna_eval_consensus_structure_pt_simple_v(alignment, pt, verbosity_level, file) + ccall((:vrna_eval_consensus_structure_pt_simple_v, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), alignment, pt, verbosity_level, file) end """ - vrna_move_is_insertion(m) + vrna_eval_loop_pt(fc, i, pt) - @brief Test whether a move is a base pair insertion +@brief Calculate energy of a loop - @param m The move to test against - @return Non-zero if the move is a base pair insertion, 0 otherwise + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param i position of covering base pair + @param pt the pair table of the secondary structure + @returns free energy of the loop in 10cal/mol ### Prototype ```c -int vrna_move_is_insertion(const vrna_move_t *m); +int vrna_eval_loop_pt(vrna_fold_compound_t *fc, int i, const short *pt); ``` """ -function vrna_move_is_insertion(m) - ccall((:vrna_move_is_insertion, libRNA), Cint, (Ptr{vrna_move_t},), m) +function vrna_eval_loop_pt(fc, i, pt) + ccall((:vrna_eval_loop_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{Cshort}), fc, i, pt) end """ - vrna_move_is_shift(m) + vrna_eval_loop_pt_v(fc, i, pt, verbosity_level) - @brief Test whether a move is a base pair shift +@brief Calculate energy of a loop - @param m The move to test against - @return Non-zero if the move is a base pair shift, 0 otherwise + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param i position of covering base pair + @param pt the pair table of the secondary structure + @param verbosity_level The level of verbosity of this function + @returns free energy of the loop in 10cal/mol ### Prototype ```c -int vrna_move_is_shift(const vrna_move_t *m); +int vrna_eval_loop_pt_v(vrna_fold_compound_t *fc, int i, const short *pt, int verbosity_level); ``` """ -function vrna_move_is_shift(m) - ccall((:vrna_move_is_shift, libRNA), Cint, (Ptr{vrna_move_t},), m) +function vrna_eval_loop_pt_v(fc, i, pt, verbosity_level) + ccall((:vrna_eval_loop_pt_v, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{Cshort}, Cint), fc, i, pt, verbosity_level) end """ - vrna_move_compare(m, b, pt) - - @brief Compare two moves - - The function compares two moves @p m and @p b and returns - whether move @p m is lexicographically smaller (-1), larger (1) - or equal to move @p b. + vrna_eval_move(fc, structure, m1, m2) - If any of the moves @p m or @p b is a shift move, this - comparison only makes sense in a structure context. Thus, - the third argument with the current structure must be provided. +@brief Calculate energy of a move (closing or opening of a base pair) - @note This function returns 0 (equality) upon any error, e.g. missing input + If the parameters m1 and m2 are negative, it is deletion (opening) + of a base pair, otherwise it is insertion (opening). - @warning Currently, shift moves are not supported! + @see vrna_eval_move_pt() - @param m The first move of the comparison - @param b The second move of the comparison - @param pt The pair table of the current structure that is compatible with both moves (maybe NULL if moves are guaranteed to be no shifts) - @return -1 if @p m < @p b, 1 if @p m > @p b, 0 otherwise + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param structure secondary structure in dot-bracket notation + @param m1 first coordinate of base pair + @param m2 second coordinate of base pair + @returns energy change of the move in kcal/mol (#INF / 100. upon any error) ### Prototype ```c -int vrna_move_compare(const vrna_move_t *m, const vrna_move_t *b, const short *pt); +float vrna_eval_move(vrna_fold_compound_t *fc, const char *structure, int m1, int m2); ``` """ -function vrna_move_compare(m, b, pt) - ccall((:vrna_move_compare, libRNA), Cint, (Ptr{vrna_move_t}, Ptr{vrna_move_t}, Ptr{Cshort}), m, b, pt) +function vrna_eval_move(fc, structure, m1, m2) + ccall((:vrna_eval_move, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, Cint), fc, structure, m1, m2) end """ - vrna_eval_structure(fc, structure) + vrna_eval_move_pt(fc, pt, m1, m2) - @brief Calculate the free energy of an already folded RNA - This function allows for energy evaluation of a given pair of structure - and sequence (alignment). - Model details, energy parameters, and possibly soft constraints are used as provided - via the parameter 'fc'. The #vrna_fold_compound_t does not need to contain any DP matrices, - but requires all most basic init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode +@brief Calculate energy of a move (closing or opening of a base pair) - @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE + If the parameters m1 and m2 are negative, it is deletion (opening) + of a base pair, otherwise it is insertion (opening). - @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_eval_covar_structure() + @see vrna_eval_move() - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param structure Secondary structure in dot-bracket notation - @return The free energy of the input structure given the input sequence in kcal/mol + @param fc A vrna_fold_compound_t containing the energy parameters and model details + @param pt the pair table of the secondary structure + @param m1 first coordinate of base pair + @param m2 second coordinate of base pair + @returns energy change of the move in 10cal/mol ### Prototype ```c -float vrna_eval_structure(vrna_fold_compound_t *fc, const char *structure); +int vrna_eval_move_pt(vrna_fold_compound_t *fc, short *pt, int m1, int m2); ``` """ -function vrna_eval_structure(fc, structure) - ccall((:vrna_eval_structure, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_eval_move_pt(fc, pt, m1, m2) + ccall((:vrna_eval_move_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cint, Cint), fc, pt, m1, m2) end """ - vrna_eval_covar_structure(fc, structure) - - @brief Calculate the pseudo energy derived by the covariance scores of a set of aligned sequences - - Consensus structure prediction is driven by covariance scores of base pairs in rows of the - provided alignment. This function allows one to retrieve the total amount of this covariance pseudo - energy scores. - The #vrna_fold_compound_t does not need to contain any DP matrices, but requires all most basic - init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound_comparative(alignment, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode - - @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_COMPARATIVE only! + vrna_eval_move_pt_simple(string, pt, m1, m2) - @see vrna_fold_compound_comparative(), vrna_eval_structure() - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param structure Secondary (consensus) structure in dot-bracket notation - @return The covariance pseudo energy score of the input structure given the input sequence alignment in kcal/mol ### Prototype ```c -float vrna_eval_covar_structure(vrna_fold_compound_t *fc, const char *structure); +int vrna_eval_move_pt_simple(const char *string, short *pt, int m1, int m2); ``` """ -function vrna_eval_covar_structure(fc, structure) - ccall((:vrna_eval_covar_structure, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_eval_move_pt_simple(string, pt, m1, m2) + ccall((:vrna_eval_move_pt_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Cint, Cint), string, pt, m1, m2) end """ - vrna_eval_structure_verbose(fc, structure, file) - - @brief Calculate the free energy of an already folded RNA and print contributions on a per-loop base. - - This function is a simplyfied version of vrna_eval_structure_v() that uses the @em default - verbosity level. + vrna_eval_move_shift_pt(fc, m, structure) - @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param structure Secondary structure in dot-bracket notation - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_structure_verbose(vrna_fold_compound_t *fc, const char *structure, FILE *file); +int vrna_eval_move_shift_pt(vrna_fold_compound_t *fc, vrna_move_t *m, short *structure); ``` """ -function vrna_eval_structure_verbose(fc, structure, file) - ccall((:vrna_eval_structure_verbose, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Libc.FILE}), fc, structure, file) +function vrna_eval_move_shift_pt(fc, m, structure) + ccall((:vrna_eval_move_shift_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_move_t}, Ptr{Cshort}), fc, m, structure) end """ - vrna_eval_structure_v(fc, structure, verbosity_level, file) + energy_of_structure(string, structure, verbosity_level) - @brief Calculate the free energy of an already folded RNA and print contributions on a per-loop base. - This function allows for detailed energy evaluation of a given sequence/structure pair. - In contrast to vrna_eval_structure() this function prints detailed energy contributions - based on individual loops to a file handle. If NULL is passed as file handle, this function - defaults to print to stdout. Any positive @p verbosity_level activates potential warning message - of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what - data is printed. A negative parameter @p verbosity_level turns off printing all together. +### Prototype +```c +; +``` +""" +function energy_of_structure(string, structure, verbosity_level) + ccall((:energy_of_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) +end - Model details, energy parameters, and possibly soft constraints are used as provided - via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, - but all the most basic init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode +""" + energy_of_struct_par(string, structure, parameters, verbosity_level) - @see vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param structure Secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_structure_v(vrna_fold_compound_t *fc, const char *structure, int verbosity_level, FILE *file); +; ``` """ -function vrna_eval_structure_v(fc, structure, verbosity_level, file) - ccall((:vrna_eval_structure_v, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), fc, structure, verbosity_level, file) +function energy_of_struct_par(string, structure, parameters, verbosity_level) + ccall((:energy_of_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) end """ - vrna_eval_structure_cstr(fc, structure, verbosity_level, output_stream) + energy_of_circ_structure(string, structure, verbosity_level) ### Prototype ```c -float vrna_eval_structure_cstr(vrna_fold_compound_t *fc, const char *structure, int verbosity_level, vrna_cstr_t output_stream); +; ``` """ -function vrna_eval_structure_cstr(fc, structure, verbosity_level, output_stream) - ccall((:vrna_eval_structure_cstr, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, vrna_cstr_t), fc, structure, verbosity_level, output_stream) +function energy_of_circ_structure(string, structure, verbosity_level) + ccall((:energy_of_circ_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) end """ - vrna_eval_structure_pt(fc, pt) - - @brief Calculate the free energy of an already folded RNA - - This function allows for energy evaluation of a given sequence/structure pair where - the structure is provided in pair_table format as obtained from vrna_ptable(). - Model details, energy parameters, and possibly soft constraints are used as provided - via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, - but all the most basic init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode + energy_of_circ_struct_par(string, structure, parameters, verbosity_level) - @see vrna_ptable(), vrna_eval_structure(), vrna_eval_structure_pt_verbose() - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param pt Secondary structure as pair_table - @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -int vrna_eval_structure_pt(vrna_fold_compound_t *fc, const short *pt); +; ``` """ -function vrna_eval_structure_pt(fc, pt) - ccall((:vrna_eval_structure_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}), fc, pt) +function energy_of_circ_struct_par(string, structure, parameters, verbosity_level) + ccall((:energy_of_circ_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) end """ - vrna_eval_structure_pt_verbose(fc, pt, file) - - @brief Calculate the free energy of an already folded RNA - - This function is a simplyfied version of vrna_eval_structure_simple_v() that uses the @em default - verbosity level. + energy_of_gquad_structure(string, structure, verbosity_level) - @see vrna_eval_structure_pt_v(), vrna_ptable(), vrna_eval_structure_pt(), vrna_eval_structure_verbose() - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param pt Secondary structure as pair_table - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -int vrna_eval_structure_pt_verbose(vrna_fold_compound_t *fc, const short *pt, FILE *file); +; ``` """ -function vrna_eval_structure_pt_verbose(fc, pt, file) - ccall((:vrna_eval_structure_pt_verbose, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Ptr{Libc.FILE}), fc, pt, file) +function energy_of_gquad_structure(string, structure, verbosity_level) + ccall((:energy_of_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) end """ - vrna_eval_structure_pt_v(fc, pt, verbosity_level, file) - - @brief Calculate the free energy of an already folded RNA - - This function allows for energy evaluation of a given sequence/structure pair where - the structure is provided in pair_table format as obtained from vrna_ptable(). - Model details, energy parameters, and possibly soft constraints are used as provided - via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, - but all the most basic init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode - In contrast to vrna_eval_structure_pt() this function prints detailed energy contributions - based on individual loops to a file handle. If NULL is passed as file handle, this function - defaults to print to stdout. Any positive @p verbosity_level activates potential warning message - of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what - data is printed. A negative parameter @p verbosity_level turns off printing all together. + energy_of_gquad_struct_par(string, structure, parameters, verbosity_level) - @see vrna_ptable(), vrna_eval_structure_pt(), vrna_eval_structure_verbose() - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param pt Secondary structure as pair_table - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in 10cal/mol ### Prototype ```c -int vrna_eval_structure_pt_v(vrna_fold_compound_t *fc, const short *pt, int verbosity_level, FILE *file); +; ``` """ -function vrna_eval_structure_pt_v(fc, pt, verbosity_level, file) - ccall((:vrna_eval_structure_pt_v, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), fc, pt, verbosity_level, file) +function energy_of_gquad_struct_par(string, structure, parameters, verbosity_level) + ccall((:energy_of_gquad_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) end """ - vrna_eval_structure_simple(string, structure) + energy_of_structure_pt(string, ptable, s, s1, verbosity_level) - @brief Calculate the free energy of an already folded RNA - This function allows for energy evaluation of a given sequence/structure pair. - In contrast to vrna_eval_structure() this function assumes default model details - and default energy parameters in order to evaluate the free energy of the secondary - structure. Therefore, it serves as a simple interface function for energy evaluation - for situations where no changes on the energy model are required. - - @see vrna_eval_structure(), vrna_eval_structure_pt(), vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose(), - - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_structure_simple(const char *string, const char *structure); +; ``` """ -function vrna_eval_structure_simple(string, structure) - ccall((:vrna_eval_structure_simple, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function energy_of_structure_pt(string, ptable, s, s1, verbosity_level) + ccall((:energy_of_structure_pt, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint), string, ptable, s, s1, verbosity_level) end """ - vrna_eval_circ_structure(string, structure) - - @brief Evaluate the free energy of a sequence/structure pair where the sequence is circular + energy_of_struct_pt_par(string, ptable, s, s1, parameters, verbosity_level) - @see vrna_eval_structure_simple(), vrna_eval_gquad_structure(), vrna_eval_circ_consensus_structure(), - vrna_eval_circ_structure_v(), vrna_eval_structure() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @return The free energy of the structure given the circular input sequence in kcal/mol ### Prototype ```c -float vrna_eval_circ_structure(const char *string, const char *structure); +; ``` """ -function vrna_eval_circ_structure(string, structure) - ccall((:vrna_eval_circ_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function energy_of_struct_pt_par(string, ptable, s, s1, parameters, verbosity_level) + ccall((:energy_of_struct_pt_par, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Ptr{vrna_param_t}, Cint), string, ptable, s, s1, parameters, verbosity_level) end """ - vrna_eval_gquad_structure(string, structure) - - @brief Evaluate the free energy of a sequence/structure pair where the structure may contain G-Quadruplexes - - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + energy_of_move(string, structure, m1, m2) - @see vrna_eval_structure_simple(), vrna_eval_circ_structure(), vrna_eval_gquad_consensus_structure(), - vrna_eval_gquad_structure_v(), vrna_eval_structure() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @return The free energy of the structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -float vrna_eval_gquad_structure(const char *string, const char *structure); +; ``` """ -function vrna_eval_gquad_structure(string, structure) - ccall((:vrna_eval_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function energy_of_move(string, structure, m1, m2) + ccall((:energy_of_move, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Cint), string, structure, m1, m2) end """ - vrna_eval_circ_gquad_structure(string, structure) - - @brief Evaluate the free energy of a sequence/structure pair where the sequence is circular and - the structure may contain G-Quadruplexes - - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + energy_of_move_pt(pt, s, s1, m1, m2) - @see vrna_eval_structure_simple(), vrna_eval_circ_gquad_consensus_structure(), - vrna_eval_circ_gquad_structure_v(), vrna_eval_structure() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @return The free energy of the structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -float vrna_eval_circ_gquad_structure(const char *string, const char *structure); +; ``` """ -function vrna_eval_circ_gquad_structure(string, structure) - ccall((:vrna_eval_circ_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function energy_of_move_pt(pt, s, s1, m1, m2) + ccall((:energy_of_move_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint, Cint), pt, s, s1, m1, m2) end """ - vrna_eval_structure_simple_verbose(string, structure, file) - - @brief Calculate the free energy of an already folded RNA and print contributions per loop. - - This function is a simplyfied version of vrna_eval_structure_simple_v() that uses the @em default - verbosity level. + loop_energy(ptable, s, s1, i) - @see vrna_eval_structure_simple_v(), vrna_eval_structure_verbose(), vrna_eval_structure_pt(), - vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_structure_simple_verbose(const char *string, const char *structure, FILE *file); +; ``` """ -function vrna_eval_structure_simple_verbose(string, structure, file) - ccall((:vrna_eval_structure_simple_verbose, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Libc.FILE}), string, structure, file) +function loop_energy(ptable, s, s1, i) + ccall((:loop_energy, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint), ptable, s, s1, i) end """ - vrna_eval_structure_simple_v(string, structure, verbosity_level, file) - - @brief Calculate the free energy of an already folded RNA and print contributions per loop. - - This function allows for detailed energy evaluation of a given sequence/structure pair. - In contrast to vrna_eval_structure() this function prints detailed energy contributions - based on individual loops to a file handle. If NULL is passed as file handle, this function - defaults to print to stdout. Any positive @p verbosity_level activates potential warning message - of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ allow for detailed control of what - data is printed. A negative parameter @p verbosity_level turns off printing all together. - - In contrast to vrna_eval_structure_verbose() this function assumes default model details - and default energy parameters in order to evaluate the free energy of the secondary - structure. Threefore, it serves as a simple interface function for energy evaluation - for situations where no changes on the energy model are required. + energy_of_struct(string, structure) - @see vrna_eval_structure_verbose(), vrna_eval_structure_pt(), vrna_eval_structure_pt_verbose(), - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_structure_simple_v(const char *string, const char *structure, int verbosity_level, FILE *file); +; ``` """ -function vrna_eval_structure_simple_v(string, structure, verbosity_level, file) - ccall((:vrna_eval_structure_simple_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) +function energy_of_struct(string, structure) + ccall((:energy_of_struct, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end """ - vrna_eval_circ_structure_v(string, structure, verbosity_level, file) - - @brief Evaluate free energy of a sequence/structure pair, assume sequence to be circular and - print contributions per loop - - This function is the same as vrna_eval_structure_simple_v() but assumes the input sequence - to be circularized. + energy_of_struct_pt(string, ptable, s, s1) - @see vrna_eval_structure_simple_v(), vrna_eval_circ_structure(), vrna_eval_structure_verbose() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_circ_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); +; ``` """ -function vrna_eval_circ_structure_v(string, structure, verbosity_level, file) - ccall((:vrna_eval_circ_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) +function energy_of_struct_pt(string, ptable, s, s1) + ccall((:energy_of_struct_pt, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}), string, ptable, s, s1) end """ - vrna_eval_gquad_structure_v(string, structure, verbosity_level, file) - - @brief Evaluate free energy of a sequence/structure pair, allow for G-Quadruplexes in the structure - and print contributions per loop - - This function is the same as vrna_eval_structure_simple_v() but allows for annotated G-Quadruplexes - in the dot-bracket structure input. - - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + energy_of_circ_struct(string, structure) - @see vrna_eval_structure_simple_v(), vrna_eval_gquad_structure(), vrna_eval_structure_verbose() - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol ### Prototype ```c -float vrna_eval_gquad_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); +; ``` """ -function vrna_eval_gquad_structure_v(string, structure, verbosity_level, file) - ccall((:vrna_eval_gquad_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) +function energy_of_circ_struct(string, structure) + ccall((:energy_of_circ_struct, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) end -""" - vrna_eval_circ_gquad_structure_v(string, structure, verbosity_level, file) +# DEPRECATED +const vrna_callback_free_auxdata = Cvoid - @brief Evaluate free energy of a sequence/structure pair, assume sequence to be circular, allow - for G-Quadruplexes in the structure, and print contributions per loop +# DEPRECATED +const vrna_callback_recursion_status = Cvoid - This function is the same as vrna_eval_structure_simple_v() but assumes the input sequence to - be circular and allows for annotated G-Quadruplexes in the dot-bracket structure input. +""" + vrna_fold_compound(sequence, md_p, options) - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + @brief Retrieve a #vrna_fold_compound_t data structure for single sequences and hybridizing sequences - @param string RNA sequence in uppercase letters - @param structure Secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in kcal/mol -### Prototype -```c -float vrna_eval_circ_gquad_structure_v(const char *string, const char *structure, int verbosity_level, FILE *file); -``` -""" -function vrna_eval_circ_gquad_structure_v(string, structure, verbosity_level, file) - ccall((:vrna_eval_circ_gquad_structure_v, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, structure, verbosity_level, file) -end + 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: @verbatim char *sequence = "GGGG&CCCC"; @endverbatim -""" - vrna_eval_consensus_structure_simple(alignment, structure) + The optional parameter @p 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 @p options may be used to specify dynamic programming (DP) matrix requirements. - @brief Calculate the free energy of an already folded RNA sequence alignment + #### Options #### + * #VRNA_OPTION_DEFAULT - @copybrief #VRNA_OPTION_DEFAULT + * #VRNA_OPTION_MFE - @copybrief #VRNA_OPTION_MFE + * #VRNA_OPTION_PF - @copybrief #VRNA_OPTION_PF + * #VRNA_OPTION_WINDOW - @copybrief #VRNA_OPTION_WINDOW - This function allows for energy evaluation for a given multiple sequence alignment - and consensus structure pair. - In contrast to vrna_eval_structure() this function assumes default model details - and default energy parameters in order to evaluate the free energy of the secondary - structure. Therefore, it serves as a simple interface function for energy evaluation - for situations where no changes on the energy model are required. + The above options may be OR-ed together. - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + If you just need the folding compound serving as a container for your data, you can simply pass + #VRNA_OPTION_DEFAULT to the @p 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 vrna_eval_covar_structure(), vrna_eval_structure(), vrna_eval_structure_pt(), - vrna_eval_structure_verbose(), vrna_eval_structure_pt_verbose() + @note The sequence string must be uppercase, and should contain only RNA (resp. DNA) alphabet depending + on what energy parameter set is used - @param alignment RNA sequence alignment in uppercase letters and hyphen ('-') to denote gaps - @param structure Consensus Secondary structure in dot-bracket notation - @return The free energy of the consensus structure given the input alignment in kcal/mol + @see vrna_fold_compound_free(), vrna_fold_compound_comparative(), #vrna_md_t + + @param sequence A single sequence, or two concatenated sequences seperated by an '&' character + @param md_p An optional set of model details + @param options The options for DP matrices memory allocation + @return A prefilled vrna_fold_compound_t ready to be used for computations (may be @p NULL on error) ### Prototype ```c -float vrna_eval_consensus_structure_simple(const char **alignment, const char *structure); +vrna_fold_compound_t * vrna_fold_compound(const char *sequence, const vrna_md_t *md_p, unsigned int options); ``` """ -function vrna_eval_consensus_structure_simple(alignment, structure) - ccall((:vrna_eval_consensus_structure_simple, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) +function vrna_fold_compound(sequence, md_p, options) + ccall((:vrna_fold_compound, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Cchar}, Ptr{vrna_md_t}, Cuint), sequence, md_p, options) end """ - vrna_eval_circ_consensus_structure(alignment, structure) + vrna_fold_compound_comparative(sequences, md_p, options) - @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair - where the sequences are circular + @brief Retrieve a #vrna_fold_compound_t data structure for sequence alignments - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. - - @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_gquad_consensus_structure(), - vrna_eval_circ_structure(), vrna_eval_circ_consensus_structure_v(), vrna_eval_structure() + This function provides an easy interface to obtain a prefilled #vrna_fold_compound_t by passing an + alignment of sequences. - @param alignment RNA sequence alignment in uppercase letters - @param structure Consensus secondary structure in dot-bracket notation - @return The free energy of the consensus structure given the circular input sequence in kcal/mol -### Prototype -```c -float vrna_eval_circ_consensus_structure(const char **alignment, const char *structure); -``` -""" -function vrna_eval_circ_consensus_structure(alignment, structure) - ccall((:vrna_eval_circ_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) -end + The optional parameter @p 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 @p options may be used to specify dynamic programming (DP) matrix requirements. -""" - vrna_eval_gquad_consensus_structure(alignment, structure) + #### Options #### + * #VRNA_OPTION_DEFAULT - @copybrief #VRNA_OPTION_DEFAULT + * #VRNA_OPTION_MFE - @copybrief #VRNA_OPTION_MFE + * #VRNA_OPTION_PF - @copybrief #VRNA_OPTION_PF + * #VRNA_OPTION_WINDOW - @copybrief #VRNA_OPTION_WINDOW - @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair - where the structure may contain G-Quadruplexes + The above options may be OR-ed together. - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + If you just need the folding compound serving as a container for your data, you can simply pass + #VRNA_OPTION_DEFAULT to the @p 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. - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + @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. - @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_circ_consensus_structure(), - vrna_eval_gquad_structure(), vrna_eval_gquad_consensus_structure_v(), vrna_eval_structure() + @see vrna_fold_compound_free(), vrna_fold_compound(), #vrna_md_t, #VRNA_OPTION_MFE, #VRNA_OPTION_PF, + #VRNA_OPTION_EVAL_ONLY, read_clustal() - @param alignment RNA sequence alignment in uppercase letters - @param structure Consensus secondary structure in dot-bracket notation - @return The free energy of the consensus structure including contributions of G-quadruplexes in kcal/mol + @param sequences A sequence alignment including 'gap' characters + @param md_p An optional set of model details + @param options The options for DP matrices memory allocation + @return A prefilled vrna_fold_compound_t ready to be used for computations (may be @p NULL on error) ### Prototype ```c -float vrna_eval_gquad_consensus_structure(const char **alignment, const char *structure); +vrna_fold_compound_t * vrna_fold_compound_comparative(const char **sequences, vrna_md_t *md_p, unsigned int options); ``` """ -function vrna_eval_gquad_consensus_structure(alignment, structure) - ccall((:vrna_eval_gquad_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) +function vrna_fold_compound_comparative(sequences, md_p, options) + ccall((:vrna_fold_compound_comparative, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Ptr{Cchar}}, Ptr{vrna_md_t}, Cuint), sequences, md_p, options) end """ - vrna_eval_circ_gquad_consensus_structure(alignment, structure) - - @brief Evaluate the free energy of a multiple sequence alignment/consensus structure pair - where the sequence is circular and the structure may contain G-Quadruplexes - - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode - - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + vrna_fold_compound_comparative2(sequences, names, orientation, start, genome_size, md_p, options) - @see vrna_eval_covar_structure(), vrna_eval_consensus_structure_simple(), vrna_eval_circ_consensus_structure(), - vrna_eval_gquad_structure(), vrna_eval_circ_gquad_consensus_structure_v(), vrna_eval_structure() - @param alignment RNA sequence alignment in uppercase letters - @param structure Consensus secondary structure in dot-bracket notation - @return The free energy of the consensus structure including contributions of G-quadruplexes in kcal/mol ### Prototype ```c -float vrna_eval_circ_gquad_consensus_structure(const char **alignment, const char *structure); +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); ``` """ -function vrna_eval_circ_gquad_consensus_structure(alignment, structure) - ccall((:vrna_eval_circ_gquad_consensus_structure, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), alignment, structure) +function vrna_fold_compound_comparative2(sequences, names, orientation, start, genome_size, md_p, options) + ccall((:vrna_fold_compound_comparative2, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Ptr{Cchar}}, Ptr{Ptr{Cchar}}, Ptr{Cuchar}, Ptr{Culonglong}, Ptr{Culonglong}, Ptr{vrna_md_t}, Cuint), sequences, names, orientation, start, genome_size, md_p, options) end """ - vrna_eval_consensus_structure_simple_verbose(alignment, structure, file) - - @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment and print - contributions per loop. - - This function is a simplyfied version of vrna_eval_consensus_structure_simple_v() that uses the - @em default verbosity level. - - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + vrna_fold_compound_TwoD(sequence, s1, s2, md_p, options) - @see vrna_eval_consensus_structure_simple_v(), vrna_eval_structure_verbose(), vrna_eval_structure_pt(), - vrna_eval_structure_pt_verbose() - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param structure Consensus secondary structure in dot-bracket notation - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the conensus structure given the aligned input sequences in kcal/mol ### Prototype ```c -float vrna_eval_consensus_structure_simple_verbose(const char **alignment, const char *structure, FILE *file); +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); ``` """ -function vrna_eval_consensus_structure_simple_verbose(alignment, structure, file) - ccall((:vrna_eval_consensus_structure_simple_verbose, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Libc.FILE}), alignment, structure, file) +function vrna_fold_compound_TwoD(sequence, s1, s2, md_p, options) + ccall((:vrna_fold_compound_TwoD, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_md_t}, Cuint), sequence, s1, s2, md_p, options) end """ - vrna_eval_consensus_structure_simple_v(alignment, structure, verbosity_level, file) - - @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment and print - contributions per loop. - - This function allows for detailed energy evaluation of a given sequence alignment/consensus - structure pair. In contrast to vrna_eval_consensus_structure_simple() this function prints - detailed energy contributions based on individual loops to a file handle. If NULL is passed - as file handle, this function defaults to print to stdout. Any positive @p verbosity_level - activates potential warning message of the energy evaluting functions, while values @f\$ \\ge 1 @f\$ - allow for detailed control of what data is printed. A negative parameter @p verbosity_level - turns off printing all together. - - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + vrna_fold_compound_prepare(fc, options) - @see vrna_eval_consensus_structure(), vrna_eval_structure() - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param structure Consensus secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the consensus structure given the sequence alignment in kcal/mol ### Prototype ```c -float vrna_eval_consensus_structure_simple_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); +int vrna_fold_compound_prepare(vrna_fold_compound_t *fc, unsigned int options); ``` """ -function vrna_eval_consensus_structure_simple_v(alignment, structure, verbosity_level, file) - ccall((:vrna_eval_consensus_structure_simple_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) +function vrna_fold_compound_prepare(fc, options) + ccall((:vrna_fold_compound_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) end """ - vrna_eval_circ_consensus_structure_v(alignment, structure, verbosity_level, file) - - @brief Evaluate the free energy of a consensus structure for an alignment of circular RNA sequences - and print contributions per loop. - - This function is identical with vrna_eval_consensus_structure_simple_v() but assumed the - aligned sequences to be circular. + vrna_fold_compound_free(fc) - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + @brief Free memory occupied by a #vrna_fold_compound_t - @see vrna_eval_consensus_structure_simple_v(), vrna_eval_circ_consensus_structure(), vrna_eval_structure() + @see vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_mx_mfe_free(), vrna_mx_pf_free() - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param structure Consensus secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the consensus structure given the sequence alignment in kcal/mol + @param fc The #vrna_fold_compound_t that is to be erased from memory ### Prototype ```c -float vrna_eval_circ_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); +void vrna_fold_compound_free(vrna_fold_compound_t *fc); ``` """ -function vrna_eval_circ_consensus_structure_v(alignment, structure, verbosity_level, file) - ccall((:vrna_eval_circ_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) +function vrna_fold_compound_free(fc) + ccall((:vrna_fold_compound_free, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_eval_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) - - @brief Evaluate the free energy of a consensus structure for an RNA sequence alignment, allow for - annotated G-Quadruplexes in the structure and print contributions per loop. - - This function is identical with vrna_eval_consensus_structure_simple_v() but allows for annotated - G-Quadruplexes in the consensus structure. + vrna_fold_compound_add_auxdata(fc, data, f) - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + @brief Add auxiliary data to the #vrna_fold_compound_t - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + 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 vrna_eval_consensus_structure_simple_v(), vrna_eval_gquad_consensus_structure(), vrna_eval_structure() + @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. - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param structure Consensus secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the consensus structure given the sequence alignment in kcal/mol + @see vrna_auxdata_free_f() + @param fc The fold_compound the arbitrary data pointer should be associated with + @param data A pointer to an arbitrary data structure + @param f A pointer to function that free's memory occupied by the arbitrary data (May be NULL) ### Prototype ```c -float vrna_eval_gquad_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); +void vrna_fold_compound_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f); ``` """ -function vrna_eval_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) - ccall((:vrna_eval_gquad_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) +function vrna_fold_compound_add_auxdata(fc, data, f) + ccall((:vrna_fold_compound_add_auxdata, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, f) end """ - vrna_eval_circ_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) - - @brief Evaluate the free energy of a consensus structure for an alignment of circular RNA sequences, - allow for annotated G-Quadruplexes in the structure and print contributions per loop. - - This function is identical with vrna_eval_consensus_structure_simple_v() but assumes the sequences in - the alignment to be circular and allows for annotated G-Quadruplexes in the consensus structure. + vrna_fold_compound_add_callback(fc, f) - G-Quadruplexes are annotated as plus signs ('+') for each G involved in the motif. Linker sequences must - be denoted by dots ('.') as they are considered unpaired. Below is an example of a 2-layer G-quadruplex: - @code{.unparsed} - GGAAGGAAAGGAGG - ++..++...++.++ - @endcode + @brief Add a recursion status callback to the #vrna_fold_compound_t - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + 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 vrna_eval_consensus_structure_simple_v(), vrna_eval_circ_gquad_consensus_structure(), vrna_eval_structure() + @see vrna_recursion_status_f(), #vrna_fold_compound_t, + #VRNA_STATUS_MFE_PRE, #VRNA_STATUS_MFE_POST, #VRNA_STATUS_PF_PRE, #VRNA_STATUS_PF_POST - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param structure Consensus secondary structure in dot-bracket notation - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the consensus structure given the sequence alignment in kcal/mol + @param fc The fold_compound the callback function should be attached to + @param f The pointer to the recursion status callback function ### Prototype ```c -float vrna_eval_circ_gquad_consensus_structure_v(const char **alignment, const char *structure, int verbosity_level, FILE *file); +void vrna_fold_compound_add_callback(vrna_fold_compound_t *fc, vrna_recursion_status_f f); ``` """ -function vrna_eval_circ_gquad_consensus_structure_v(alignment, structure, verbosity_level, file) - ccall((:vrna_eval_circ_gquad_consensus_structure_v, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), alignment, structure, verbosity_level, file) +function vrna_fold_compound_add_callback(fc, f) + ccall((:vrna_fold_compound_add_callback, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_recursion_status_f), fc, f) end +# typedef void ( * vrna_heat_capacity_f ) ( float temp , float heat_capacity , void * data ) """ - vrna_eval_structure_pt_simple(string, pt) + @brief The callback for heat capacity predictions - @brief Calculate the free energy of an already folded RNA + @callback + @parblock + This function will be called for each evaluated temperature in the heat capacity prediction. + @endparblock - In contrast to vrna_eval_structure_pt() this function assumes default model details - and default energy parameters in order to evaluate the free energy of the secondary - structure. Threefore, it serves as a simple interface function for energy evaluation - for situations where no changes on the energy model are required. + @see vrna_heat_capacity_cb() - @see vrna_ptable(), vrna_eval_structure_simple(), vrna_eval_structure_pt() + @param temp The current temperature this results corresponds to in °C + @param heat_capacity The heat capacity in Kcal/(Mol * K) + @param data Some arbitrary data pointer passed through by the function executing the callback +""" +const vrna_heat_capacity_f = Ptr{Cvoid} + +# DEPRECATED +const vrna_heat_capacity_callback = Cvoid - @param string RNA sequence in uppercase letters - @param pt Secondary structure as pair_table - @return The free energy of the input structure given the input sequence in 10cal/mol -### Prototype -```c -int vrna_eval_structure_pt_simple(const char *string, const short *pt); -``` """ -function vrna_eval_structure_pt_simple(string, pt) - ccall((:vrna_eval_structure_pt_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}), string, pt) + vrna_heat_capacity_s + + @brief A single result from heat capacity computations + + @see vrna_heat_capacity() +""" +struct vrna_heat_capacity_s + temperature::Cfloat + heat_capacity::Cfloat end """ - vrna_eval_structure_pt_simple_verbose(string, pt, file) + @brief A single result from heat capacity computations - @brief Calculate the free energy of an already folded RNA + This is a convenience typedef for #vrna_heat_capacity_s, i.e. results as obtained from vrna_heat_capacity() +""" +const vrna_heat_capacity_t = vrna_heat_capacity_s - This function is a simplyfied version of vrna_eval_structure_pt_simple_v() that uses the @em default - verbosity level. +""" + vrna_heat_capacity(fc, T_min, T_max, T_increment, mpoints) - @see vrna_eval_structure_pt_simple_v(), vrna_ptable(), vrna_eval_structure_pt_verbose(), vrna_eval_structure_simple() + @brief Compute the specific heat for an RNA - @param string RNA sequence in uppercase letters - @param pt Secondary structure as pair_table - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in 10cal/mol + This function computes an RNAs specific heat in a given temperature range + from the partition function by numeric differentiation. The result is returned + as a list of pairs of temperature in °C and specific heat in Kcal/(Mol*K). + + Users can specify the temperature range for the computation from @p T_min to + @p T_max, as well as the increment step size @p T_increment. The latter also determines + how many times the partition function is computed. Finally, the parameter @p mpoints + determines how smooth the curve should be. The algorithm itself fits a parabola + to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this + parameter produces a smoother curve. + + @see vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s + + @param fc The #vrna_fold_compound_t with the RNA sequence to analyze + @param T_min Lowest temperature in °C + @param T_max Highest temperature in °C + @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) + @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) + @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. + The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min ### Prototype ```c -int vrna_eval_structure_pt_simple_verbose(const char *string, const short *pt, FILE *file); +vrna_heat_capacity_t * vrna_heat_capacity(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints); ``` """ -function vrna_eval_structure_pt_simple_verbose(string, pt, file) - ccall((:vrna_eval_structure_pt_simple_verbose, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Libc.FILE}), string, pt, file) +function vrna_heat_capacity(fc, T_min, T_max, T_increment, mpoints) + ccall((:vrna_heat_capacity, libRNA), Ptr{vrna_heat_capacity_t}, (Ptr{vrna_fold_compound_t}, Cfloat, Cfloat, Cfloat, Cuint), fc, T_min, T_max, T_increment, mpoints) end """ - vrna_eval_structure_pt_simple_v(string, pt, verbosity_level, file) + vrna_heat_capacity_cb(fc, T_min, T_max, T_increment, mpoints, cb, data) - @brief Calculate the free energy of an already folded RNA + @brief Compute the specific heat for an RNA (callback variant) - This function allows for energy evaluation of a given sequence/structure pair where - the structure is provided in pair_table format as obtained from vrna_ptable(). - Model details, energy parameters, and possibly soft constraints are used as provided - via the parameter 'fc'. The fold_compound does not need to contain any DP matrices, - but all the most basic init values as one would get from a call like this: - @code{.c} -fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_EVAL_ONLY); - @endcode - In contrast to vrna_eval_structure_pt_verbose() this function assumes default model details - and default energy parameters in order to evaluate the free energy of the secondary - structure. Threefore, it serves as a simple interface function for energy evaluation - for situations where no changes on the energy model are required. + Similar to vrna_heat_capacity(), this function computes an RNAs specific heat in + a given temperature range from the partition function by numeric differentiation. + Instead of returning a list of temperature/specific heat pairs, however, this + function returns the individual results through a callback mechanism. The provided + function will be called for each result and passed the corresponding temperature + and specific heat values along with the arbitrary data as provided through the + @p data pointer argument. - @see vrna_ptable(), vrna_eval_structure_pt_v(), vrna_eval_structure_simple() + Users can specify the temperature range for the computation from @p T_min to + @p T_max, as well as the increment step size @p T_increment. The latter also determines + how many times the partition function is computed. Finally, the parameter @p mpoints + determines how smooth the curve should be. The algorithm itself fits a parabola + to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this + parameter produces a smoother curve. - @param string RNA sequence in uppercase letters - @param pt Secondary structure as pair_table - @param verbosity_level The level of verbosity of this function - @param file A file handle where this function should print to (may be NULL). - @return The free energy of the input structure given the input sequence in 10cal/mol + @see vrna_heat_capacity(), vrna_heat_capacity_f + + @param fc The #vrna_fold_compound_t with the RNA sequence to analyze + @param T_min Lowest temperature in °C + @param T_max Highest temperature in °C + @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) + @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) + @param cb The user-defined callback function that receives the individual results + @param data An arbitrary data structure that will be passed to the callback in conjunction with the results + @return Returns 0 upon failure, and non-zero otherwise ### Prototype ```c -int vrna_eval_structure_pt_simple_v(const char *string, const short *pt, int verbosity_level, FILE *file); +int vrna_heat_capacity_cb(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints, vrna_heat_capacity_f cb, void *data); ``` """ -function vrna_eval_structure_pt_simple_v(string, pt, verbosity_level, file) - ccall((:vrna_eval_structure_pt_simple_v, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), string, pt, verbosity_level, file) +function vrna_heat_capacity_cb(fc, T_min, T_max, T_increment, mpoints, cb, data) + ccall((:vrna_heat_capacity_cb, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cfloat, Cfloat, Cfloat, Cuint, vrna_heat_capacity_f, Ptr{Cvoid}), fc, T_min, T_max, T_increment, mpoints, cb, data) end """ - vrna_eval_consensus_structure_pt_simple(alignment, pt) + vrna_heat_capacity_simple(sequence, T_min, T_max, T_increment, mpoints) - @brief Evaluate the Free Energy of a Consensus Secondary Structure given a Sequence Alignment + @brief Compute the specific heat for an RNA (simplified variant) - @note The free energy returned from this function already includes the covariation - pseudo energies that is used fir comparative structure prediction within this - library. + Similar to vrna_heat_capacity(), this function computes an RNAs specific heat + in a given temperature range from the partition function by numeric differentiation. + This simplified version, however, only requires the RNA sequence as input instead of + a vrna_fold_compound_t data structure. The result is returned as a list of pairs of + temperature in °C and specific heat in Kcal/(Mol*K). - @see vrna_eval_consensus_structure_simple(), vrna_eval_structure_pt(), vrna_eval_structure(), - vrna_eval_covar_structure() + Users can specify the temperature range for the computation from @p T_min to + @p T_max, as well as the increment step size @p T_increment. The latter also determines + how many times the partition function is computed. Finally, the parameter @p mpoints + determines how smooth the curve should be. The algorithm itself fits a parabola + to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this + parameter produces a smoother curve. - @param alignment RNA sequence alignment in uppercase letters. Gaps are denoted by hyphens ('-') - @param pt Secondary structure in pair table format - @return Free energy of the consensus structure in 10cal/mol + @see vrna_heat_capacity(), vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s + + @param sequence The RNA sequence input (must be uppercase) + @param T_min Lowest temperature in °C + @param T_max Highest temperature in °C + @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) + @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) + @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. + The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min ### Prototype ```c -int vrna_eval_consensus_structure_pt_simple(const char **alignment, const short *pt); +vrna_heat_capacity_t * vrna_heat_capacity_simple(const char *sequence, float T_min, float T_max, float T_increment, unsigned int mpoints); ``` """ -function vrna_eval_consensus_structure_pt_simple(alignment, pt) - ccall((:vrna_eval_consensus_structure_pt_simple, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}), alignment, pt) +function vrna_heat_capacity_simple(sequence, T_min, T_max, T_increment, mpoints) + ccall((:vrna_heat_capacity_simple, libRNA), Ptr{vrna_heat_capacity_t}, (Ptr{Cchar}, Cfloat, Cfloat, Cfloat, Cuint), sequence, T_min, T_max, T_increment, mpoints) end """ - vrna_eval_consensus_structure_pt_simple_verbose(alignment, pt, file) + inverse_fold(start, target) + + \\brief Find sequences with predefined structure + This function searches for a sequence with minimum free energy structure + provided in the parameter 'target', starting with sequence 'start'. + It returns 0 if the search was successful, otherwise a structure distance + in terms of the energy difference between the search result and the actual + target 'target' is returned. The found sequence is returned in 'start'. + If #give_up is set to 1, the function will return as soon as it is + clear that the search will be unsuccessful, this speeds up the algorithm + if you are only interested in exact solutions. + \\param start The start sequence + \\param target The target secondary structure in dot-bracket notation + \\return The distance to the target in case a search was unsuccessful, 0 otherwise ### Prototype ```c -int vrna_eval_consensus_structure_pt_simple_verbose(const char **alignment, const short *pt, FILE *file); +float inverse_fold( char *start, const char *target); ``` """ -function vrna_eval_consensus_structure_pt_simple_verbose(alignment, pt, file) - ccall((:vrna_eval_consensus_structure_pt_simple_verbose, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}, Ptr{Libc.FILE}), alignment, pt, file) +function inverse_fold(start, target) + ccall((:inverse_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), start, target) end """ - vrna_eval_consensus_structure_pt_simple_v(alignment, pt, verbosity_level, file) + inverse_pf_fold(start, target) + + \\brief Find sequence that maximizes probability of a predefined structure + This function searches for a sequence with maximum probability to fold into + the provided structure 'target' using the partition function algorithm. + It returns \\f\$-kT \\cdot \\log(p)\\f\$ where \\f\$p\\f\$ is the frequency of 'target' in + the ensemble of possible structures. This is usually much slower than + inverse_fold(). + \\param start The start sequence + \\param target The target secondary structure in dot-bracket notation + \\return The distance to the target in case a search was unsuccessful, 0 otherwise ### Prototype ```c -int vrna_eval_consensus_structure_pt_simple_v(const char **alignment, const short *pt, int verbosity_level, FILE *file); +float inverse_pf_fold(char *start, const char *target); ``` """ -function vrna_eval_consensus_structure_pt_simple_v(alignment, pt, verbosity_level, file) - ccall((:vrna_eval_consensus_structure_pt_simple_v, libRNA), Cint, (Ptr{Ptr{Cchar}}, Ptr{Cshort}, Cint, Ptr{Libc.FILE}), alignment, pt, verbosity_level, file) +function inverse_pf_fold(start, target) + ccall((:inverse_pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), start, target) end +# typedef void ( * vrna_move_update_f ) ( vrna_fold_compound_t * fc , vrna_move_t neighbor , unsigned int state , void * data ) """ - vrna_eval_loop_pt(fc, i, pt) + @brief Prototype of the neighborhood update callback -@brief Calculate energy of a loop + @see vrna_move_neighbor_diff_cb(), #VRNA_NEIGHBOR_CHANGE, #VRNA_NEIGHBOR_INVALID, #VRNA_NEIGHBOR_NEW - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param i position of covering base pair - @param pt the pair table of the secondary structure - @returns free energy of the loop in 10cal/mol -### Prototype -```c -int vrna_eval_loop_pt(vrna_fold_compound_t *fc, int i, const short *pt); -``` + @param fc The fold compound the calling function is working on + @param neighbor The move that generates the (changed or new) neighbor + @param state The state of the neighbor (move) as supplied by argument @p neighbor + @param data Some arbitrary data pointer as passed to vrna_move_neighbor_diff_cb() """ -function vrna_eval_loop_pt(fc, i, pt) - ccall((:vrna_eval_loop_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{Cshort}), fc, i, pt) -end +const vrna_move_update_f = Ptr{Cvoid} + +# DEPRECATED +const vrna_callback_move_update = Cvoid """ - vrna_eval_loop_pt_v(fc, i, pt, verbosity_level) + vrna_loopidx_update(loopidx, pt, length, m) -@brief Calculate energy of a loop +@brief Alters the loopIndices array that was constructed with vrna_loopidx_from_ptable(). - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param i position of covering base pair - @param pt the pair table of the secondary structure - @param verbosity_level The level of verbosity of this function - @returns free energy of the loop in 10cal/mol +The loopIndex of the current move will be inserted. +The correctness of the input will not be checked because the speed should be optimized. + +@param[in,out] loopidx The loop index data structure that needs an update +@param[in] pt A pair table on which the move will be executed +@param length The length of the structure +@param[in] m The move that is applied to the current structure ### Prototype ```c -int vrna_eval_loop_pt_v(vrna_fold_compound_t *fc, int i, const short *pt, int verbosity_level); +void vrna_loopidx_update(int *loopidx, const short *pt, int length, const vrna_move_t *m); ``` """ -function vrna_eval_loop_pt_v(fc, i, pt, verbosity_level) - ccall((:vrna_eval_loop_pt_v, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{Cshort}, Cint), fc, i, pt, verbosity_level) +function vrna_loopidx_update(loopidx, pt, length, m) + ccall((:vrna_loopidx_update, libRNA), Cvoid, (Ptr{Cint}, Ptr{Cshort}, Cint, Ptr{vrna_move_t}), loopidx, pt, length, m) end """ - vrna_eval_move(fc, structure, m1, m2) + vrna_neighbors(fc, pt, options) -@brief Calculate energy of a move (closing or opening of a base pair) +@brief Generate neighbors of a secondary structure - If the parameters m1 and m2 are negative, it is deletion (opening) - of a base pair, otherwise it is insertion (opening). +This function allows one to generate all structural neighbors (according to a particular move set) +of an RNA secondary structure. The neighborhood is then returned as a list of transitions / moves +required to transform the current structure into the actual neighbor. - @see vrna_eval_move_pt() +@see vrna_neighbors_successive(), vrna_move_apply(), + #VRNA_MOVESET_INSERTION, #VRNA_MOVESET_DELETION, #VRNA_MOVESET_SHIFT, #VRNA_MOVESET_DEFAULT - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param structure secondary structure in dot-bracket notation - @param m1 first coordinate of base pair - @param m2 second coordinate of base pair - @returns energy change of the move in kcal/mol (#INF / 100. upon any error) +@param[in] fc A vrna_fold_compound_t containing the energy parameters and model details +@param[in] pt The pair table representation of the structure +@param options Options to modify the behavior of this function, e.g. available move set +@return Neighbors as a list of moves / transitions (the last element in the list has both of its fields set to 0) ### Prototype ```c -float vrna_eval_move(vrna_fold_compound_t *fc, const char *structure, int m1, int m2); +vrna_move_t * vrna_neighbors(vrna_fold_compound_t *fc, const short *pt, unsigned int options); ``` """ -function vrna_eval_move(fc, structure, m1, m2) - ccall((:vrna_eval_move, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cint, Cint), fc, structure, m1, m2) +function vrna_neighbors(fc, pt, options) + ccall((:vrna_neighbors, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cuint), fc, pt, options) end """ - vrna_eval_move_pt(fc, pt, m1, m2) - + vrna_neighbors_successive(fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) -@brief Calculate energy of a move (closing or opening of a base pair) +@brief Generate neighbors of a secondary structure (the fast way) - If the parameters m1 and m2 are negative, it is deletion (opening) - of a base pair, otherwise it is insertion (opening). +This function implements a fast way to generate all neighbors of a secondary structure +that results from successive applications of individual moves. The speed-up results from +updating an already known list of valid neighbors before the individual move towards the +current structure took place. In essence, this function removes neighbors that are not +accessible anymore and inserts neighbors emerging after a move took place. - @see vrna_eval_move() +@see vrna_neighbors(), vrna_move_apply(), + #VRNA_MOVESET_INSERTION, #VRNA_MOVESET_DELETION, #VRNA_MOVESET_SHIFT, #VRNA_MOVESET_DEFAULT - @param fc A vrna_fold_compound_t containing the energy parameters and model details - @param pt the pair table of the secondary structure - @param m1 first coordinate of base pair - @param m2 second coordinate of base pair - @returns energy change of the move in 10cal/mol +@param[in] fc A vrna_fold_compound_t containing the energy parameters and model details +@param[in] curr_move The move that was/will be applied to @p prev_pt +@param[in] prev_pt A pair table representation of the structure before @p curr_move is/was applied +@param[in] prev_neighbors The list of neighbors of @p prev_pt +@param size_prev_neighbors The size of @p prev_neighbors, i.e. the lists length +@param[out] size_neighbors A pointer to store the size / length of the new neighbor list +@param options Options to modify the behavior of this function, e.g. available move set +@return Neighbors as a list of moves / transitions (the last element in the list has both of its fields set to 0) ### Prototype ```c -int vrna_eval_move_pt(vrna_fold_compound_t *fc, short *pt, int m1, int m2); +vrna_move_t * vrna_neighbors_successive(const vrna_fold_compound_t *fc, const vrna_move_t *curr_move, const short *prev_pt, const vrna_move_t *prev_neighbors, int size_prev_neighbors, int *size_neighbors, unsigned int options); ``` """ -function vrna_eval_move_pt(fc, pt, m1, m2) - ccall((:vrna_eval_move_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cint, Cint), fc, pt, m1, m2) +function vrna_neighbors_successive(fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) + ccall((:vrna_neighbors_successive, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{vrna_move_t}, Ptr{Cshort}, Ptr{vrna_move_t}, Cint, Ptr{Cint}, Cuint), fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) end """ - vrna_eval_move_pt_simple(string, pt, m1, m2) + vrna_move_neighbor_diff_cb(fc, ptable, move, cb, data, options) + + @brief Apply a move to a secondary structure and indicate which neighbors have changed consequentially + + This function applies a move to a secondary structure and explores the local neighborhood of the + affected loop. Any changes to previously compatible neighbors that have been affected by this loop + will be reported through a callback function. In particular, any of the three cases might appear: + - A previously available neighbor move has changed, usually the free energy change of the move (#VRNA_NEIGHBOR_CHANGE) + - A previously available neighbor move became invalid (#VRNA_NEIGHBOR_INVALID) + - A new neighbor move becomes available (#VRNA_NEIGHBOR_NEW) + @see vrna_move_neighbor_diff(), #VRNA_NEIGHBOR_CHANGE, #VRNA_NEIGHBOR_INVALID, #VRNA_NEIGHBOR_NEW, + #vrna_move_update_f, #VRNA_MOVE_NO_APPLY + @param fc A fold compound for the RNA sequence(s) that this function operates on + @param ptable The current structure as pair table + @param move The move to apply + @param cb The address of the callback function that is passed the neighborhood changes + @param data An arbitrary data pointer that will be passed through to the callback function @p cb + @param options Options to modify the behavior of this function, .e.g available move set + @return Non-zero on success, 0 otherwise ### Prototype ```c -int vrna_eval_move_pt_simple(const char *string, short *pt, int m1, int m2); +int vrna_move_neighbor_diff_cb(vrna_fold_compound_t *fc, short *ptable, vrna_move_t move, vrna_move_update_f cb, void *data, unsigned int options); ``` """ -function vrna_eval_move_pt_simple(string, pt, m1, m2) - ccall((:vrna_eval_move_pt_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Cint, Cint), string, pt, m1, m2) +function vrna_move_neighbor_diff_cb(fc, ptable, move, cb, data, options) + ccall((:vrna_move_neighbor_diff_cb, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, vrna_move_t, vrna_move_update_f, Ptr{Cvoid}, Cuint), fc, ptable, move, cb, data, options) end """ - vrna_eval_move_shift_pt(fc, m, structure) + vrna_move_neighbor_diff(fc, ptable, move, invalid_moves, options) + + @brief Apply a move to a secondary structure and indicate which neighbors have changed consequentially + Similar to vrna_move_neighbor_diff_cb(), this function applies a move to a secondary structure and + reports back the neighbors of the current structure become affected by this move. Instead of executing + a callback for each of the affected neighbors, this function compiles two lists of neighbor moves, one + that is returned and consists of all moves that are novel or may have changed in energy, and a second, + @p invalid_moves, that consists of all the neighbor moves that become invalid, respectively. + @param fc A fold compound for the RNA sequence(s) that this function operates on + @param ptable The current structure as pair table + @param move The move to apply + @param invalid_moves The address of a move list where the function stores those moves that become invalid + @param options Options to modify the behavior of this function, .e.g available move set + @return A list of moves that might have changed in energy or are novel compared to the structure before application of the move ### Prototype ```c -int vrna_eval_move_shift_pt(vrna_fold_compound_t *fc, vrna_move_t *m, short *structure); +vrna_move_t * vrna_move_neighbor_diff(vrna_fold_compound_t *fc, short *ptable, vrna_move_t move, vrna_move_t **invalid_moves, unsigned int options); ``` """ -function vrna_eval_move_shift_pt(fc, m, structure) - ccall((:vrna_eval_move_shift_pt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_move_t}, Ptr{Cshort}), fc, m, structure) +function vrna_move_neighbor_diff(fc, ptable, move, invalid_moves, options) + ccall((:vrna_move_neighbor_diff, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, vrna_move_t, Ptr{Ptr{vrna_move_t}}, Cuint), fc, ptable, move, invalid_moves, options) end """ - energy_of_structure(string, structure, verbosity_level) + vrna_MEA(fc, gamma, mea) + @brief Compute a MEA (maximum expected accuracy) structure -### Prototype -```c -; -``` -""" -function energy_of_structure(string, structure, verbosity_level) - ccall((:energy_of_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) -end + The algorithm maximizes the expected accuracy -""" - energy_of_struct_par(string, structure, parameters, verbosity_level) + @f[ + A(S) = \\sum_{(i,j) \\in S} 2 \\gamma p_{ij} + \\sum_{i \\notin S} p^u_i + @f] + + Higher values of @f\$\\gamma@f\$ result in more base pairs of lower + probability and thus higher sensitivity. Low values of @f\$\\gamma@f\$ result in structures + containing only highly likely pairs (high specificity). + The code of the MEA function also demonstrates the use of sparse dynamic + programming scheme to reduce the time and memory complexity of folding. + + @pre vrna_pf() must be executed on input parameter @p fc + @ingroup mea_fold + @param fc The fold compound data structure with pre-filled base pair probability matrix + @param gamma The weighting factor for base pairs vs. unpaired nucleotides + @param mea A pointer to a variable where the MEA value will be written to + @return An MEA structure (or NULL on any error) ### Prototype ```c -; +char * vrna_MEA(vrna_fold_compound_t *fc, double gamma, float *mea); ``` """ -function energy_of_struct_par(string, structure, parameters, verbosity_level) - ccall((:energy_of_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) +function vrna_MEA(fc, gamma, mea) + ccall((:vrna_MEA, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cdouble, Ptr{Cfloat}), fc, gamma, mea) end """ - energy_of_circ_structure(string, structure, verbosity_level) + vrna_MEA_from_plist(plist_, sequence, gamma, md, mea) + @brief Compute a MEA (maximum expected accuracy) structure from a list of probabilities -### Prototype -```c -; -``` -""" -function energy_of_circ_structure(string, structure, verbosity_level) - ccall((:energy_of_circ_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) -end + The algorithm maximizes the expected accuracy -""" - energy_of_circ_struct_par(string, structure, parameters, verbosity_level) + @f[ + A(S) = \\sum_{(i,j) \\in S} 2 \\gamma p_{ij} + \\sum_{i \\notin S} p^u_i + @f] + + Higher values of @f\$\\gamma@f\$ result in more base pairs of lower + probability and thus higher sensitivity. Low values of @f\$\\gamma@f\$ result in structures + containing only highly likely pairs (high specificity). + The code of the MEA function also demonstrates the use of sparse dynamic + programming scheme to reduce the time and memory complexity of folding. + + @note The unpaired probabilities @f\$p^u_i = 1 - \\sum_{j \\neq i} p_{ij}@f\$ are usually + computed from the supplied pairing probabilities @f\$p_{ij}@f\$ as stored in @p plist + entries of type #VRNA_PLIST_TYPE_BASEPAIR. To overwrite individual @f\$p^u_o@f\$ + values simply add entries with type #VRNA_PLIST_TYPE_UNPAIRED
+ To include G-Quadruplex support, the corresponding field in @p md must be set. + @ingroup mea_fold + @param plist A list of base pair probabilities the MEA structure is computed from + @param sequence The RNA sequence that corresponds to the list of probability values + @param gamma The weighting factor for base pairs vs. unpaired nucleotides + @param md A model details data structure (maybe NULL) + @param mea A pointer to a variable where the MEA value will be written to + @return An MEA structure (or NULL on any error) ### Prototype ```c -; +char * vrna_MEA_from_plist(vrna_ep_t *plist, const char *sequence, double gamma, vrna_md_t *md, float *mea); ``` """ -function energy_of_circ_struct_par(string, structure, parameters, verbosity_level) - ccall((:energy_of_circ_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) +function vrna_MEA_from_plist(plist_, sequence, gamma, md, mea) + ccall((:vrna_MEA_from_plist, libRNA), Ptr{Cchar}, (Ptr{vrna_ep_t}, Ptr{Cchar}, Cdouble, Ptr{vrna_md_t}, Ptr{Cfloat}), plist_, sequence, gamma, md, mea) end """ - energy_of_gquad_structure(string, structure, verbosity_level) + MEA(p, structure, gamma) ### Prototype @@ -7204,12 +7096,12 @@ end ; ``` """ -function energy_of_gquad_structure(string, structure, verbosity_level) - ccall((:energy_of_gquad_structure, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint), string, structure, verbosity_level) +function MEA(p, structure, gamma) + ccall((:MEA, libRNA), Cfloat, (Ptr{plist}, Ptr{Cchar}, Cdouble), p, structure, gamma) end """ - energy_of_gquad_struct_par(string, structure, parameters, verbosity_level) + MEA_seq(p, sequence, structure, gamma, pf) ### Prototype @@ -7217,25 +7109,48 @@ end ; ``` """ -function energy_of_gquad_struct_par(string, structure, parameters, verbosity_level) - ccall((:energy_of_gquad_struct_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint), string, structure, parameters, verbosity_level) +function MEA_seq(p, sequence, structure, gamma, pf) + ccall((:MEA_seq, libRNA), Cfloat, (Ptr{plist}, Ptr{Cchar}, Ptr{Cchar}, Cdouble, Ptr{vrna_exp_param_t}), p, sequence, structure, gamma, pf) end """ - energy_of_structure_pt(string, ptable, s, s1, verbosity_level) + vrna_mfe(fc, structure) + + @brief Compute minimum free energy and an appropriate secondary + structure of an RNA sequence, or RNA sequence alignment + + Depending on the type of the provided #vrna_fold_compound_t, this function + predicts the MFE for a single sequence (or connected component of multiple + sequences), or an averaged MFE for a sequence alignment. + If backtracking is activated, it also constructs the corresponding secondary + structure, or consensus structure. + Therefore, the second parameter, @a structure, has to point to an allocated + block of memory with a size of at least @f\$\\mathrm{strlen}(\\mathrm{sequence})+1@f\$ to + store the backtracked MFE structure. (For consensus structures, this is the length of + the alignment + 1. If @p NULL is passed, no backtracking will be performed. + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + @see #vrna_fold_compound_t, vrna_fold_compound(), vrna_fold(), vrna_circfold(), + vrna_fold_compound_comparative(), vrna_alifold(), vrna_circalifold() + + @param fc fold compound + @param structure A pointer to the character array where the + secondary structure in dot-bracket notation will be written to (Maybe NULL) + @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -; +float vrna_mfe(vrna_fold_compound_t *fc, char *structure); ``` """ -function energy_of_structure_pt(string, ptable, s, s1, verbosity_level) - ccall((:energy_of_structure_pt, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint), string, ptable, s, s1, verbosity_level) +function vrna_mfe(fc, structure) + ccall((:vrna_mfe, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - energy_of_struct_pt_par(string, ptable, s, s1, parameters, verbosity_level) + vrna_mfe_dimer(fc, structure) ### Prototype @@ -7243,64 +7158,138 @@ end ; ``` """ -function energy_of_struct_pt_par(string, ptable, s, s1, parameters, verbosity_level) - ccall((:energy_of_struct_pt_par, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Ptr{vrna_param_t}, Cint), string, ptable, s, s1, parameters, verbosity_level) +function vrna_mfe_dimer(fc, structure) + ccall((:vrna_mfe_dimer, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - energy_of_move(string, structure, m1, m2) + vrna_fold(sequence, structure) + + @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for an RNA sequence + + This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for an + RNA sequence using default options. Memory required for dynamic programming (DP) matrices will + be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled + matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_mfe(), + and the data structure #vrna_fold_compound_t instead. + + @see vrna_circfold(), vrna_mfe() + @param sequence RNA sequence + @param structure A pointer to the character array where the + secondary structure in dot-bracket notation will be written to + @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -; +float vrna_fold(const char *sequence, char *structure); ``` """ -function energy_of_move(string, structure, m1, m2) - ccall((:energy_of_move, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Cint, Cint), string, structure, m1, m2) +function vrna_fold(sequence, structure) + ccall((:vrna_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) end """ - energy_of_move_pt(pt, s, s1, m1, m2) + vrna_circfold(sequence, structure) + + @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for a circular RNA sequence + + This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for a + circular RNA sequence using default options. Memory required for dynamic programming (DP) matrices will + be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled + matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. + Folding of circular RNA sequences is handled as a post-processing step of the forward + recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. + + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_mfe(), + and the data structure #vrna_fold_compound_t instead. + + @see vrna_fold(), vrna_mfe() + @param sequence RNA sequence + @param structure A pointer to the character array where the + secondary structure in dot-bracket notation will be written to + @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -; +float vrna_circfold(const char *sequence, char *structure); ``` """ -function energy_of_move_pt(pt, s, s1, m1, m2) - ccall((:energy_of_move_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint, Cint), pt, s, s1, m1, m2) +function vrna_circfold(sequence, structure) + ccall((:vrna_circfold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) end """ - loop_energy(ptable, s, s1, i) + vrna_alifold(sequences, structure) + + @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure + for an RNA sequence alignment using a comparative method + + This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary + structure for an RNA sequence alignment using default options. Memory required for dynamic programming + (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of this function, the + recursively filled matrices are not available any more for any post-processing, e.g. suboptimal + backtracking, etc. + + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_mfe(), + and the data structure #vrna_fold_compound_t instead. + @see vrna_circalifold(), vrna_mfe() + @param sequences RNA sequence alignment + @param structure A pointer to the character array where the + secondary structure in dot-bracket notation will be written to + @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -; +float vrna_alifold(const char **sequences, char *structure); ``` """ -function loop_energy(ptable, s, s1, i) - ccall((:loop_energy, libRNA), Cint, (Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}, Cint), ptable, s, s1, i) +function vrna_alifold(sequences, structure) + ccall((:vrna_alifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), sequences, structure) end """ - energy_of_struct(string, structure) + vrna_circalifold(sequences, structure) + + @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure + for a sequence alignment of circular RNAs using a comparative method + + This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary + structure for an RNA sequence alignment using default options. Memory required for dynamic programming + (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of this function, the + recursively filled matrices are not available any more for any post-processing, e.g. suboptimal + backtracking, etc. + + Folding of circular RNA sequences is handled as a post-processing step of the forward + recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. + + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_mfe(), + and the data structure #vrna_fold_compound_t instead. + @see vrna_alifold(), vrna_mfe() + @param sequences Sequence alignment of circular RNAs + @param structure A pointer to the character array where the + secondary structure in dot-bracket notation will be written to + @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -; +float vrna_circalifold(const char **sequences, char *structure); ``` """ -function energy_of_struct(string, structure) - ccall((:energy_of_struct, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function vrna_circalifold(sequences, structure) + ccall((:vrna_circalifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), sequences, structure) end """ - energy_of_struct_pt(string, ptable, s, s1) + vrna_cofold(sequence, structure) ### Prototype @@ -7308,654 +7297,549 @@ end ; ``` """ -function energy_of_struct_pt(string, ptable, s, s1) - ccall((:energy_of_struct_pt, libRNA), Cint, (Ptr{Cchar}, Ptr{Cshort}, Ptr{Cshort}, Ptr{Cshort}), string, ptable, s, s1) +function vrna_cofold(sequence, structure) + ccall((:vrna_cofold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) end """ - energy_of_circ_struct(string, structure) - + vrna_backtrack_from_intervals(fc, bp_stack, bt_stack, s) + @brief ### Prototype ```c -; +int vrna_backtrack_from_intervals(vrna_fold_compound_t *fc, vrna_bp_stack_t *bp_stack, sect bt_stack[], int s); ``` """ -function energy_of_circ_struct(string, structure) - ccall((:energy_of_circ_struct, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), string, structure) +function vrna_backtrack_from_intervals(fc, bp_stack, bt_stack, s) + ccall((:vrna_backtrack_from_intervals, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_bp_stack_t}, Ptr{sect}, Cint), fc, bp_stack, bt_stack, s) end -# DEPRECATED -const vrna_callback_free_auxdata = Cvoid - -# DEPRECATED -const vrna_callback_recursion_status = Cvoid - """ - vrna_fold_compound(sequence, md_p, options) - - @brief 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: @verbatim char *sequence = "GGGG&CCCC"; @endverbatim + vrna_backtrack5(fc, length, structure) - The optional parameter @p 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 @p options may be used to specify dynamic programming (DP) matrix requirements. + @brief Backtrack an MFE (sub)structure - #### Options #### - * #VRNA_OPTION_DEFAULT - @copybrief #VRNA_OPTION_DEFAULT - * #VRNA_OPTION_MFE - @copybrief #VRNA_OPTION_MFE - * #VRNA_OPTION_PF - @copybrief #VRNA_OPTION_PF - * #VRNA_OPTION_WINDOW - @copybrief #VRNA_OPTION_WINDOW + This function allows one to backtrack the MFE structure for a (sub)sequence - The above options may be OR-ed together. + @note On error, the function returns #INF / 100. and stores the empty string + in @p structure. - If you just need the folding compound serving as a container for your data, you can simply pass - #VRNA_OPTION_DEFAULT to the @p 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. + @pre Requires pre-filled MFE dynamic programming matrices, i.e. one has to call vrna_mfe() + prior to calling this function - @note The sequence string must be uppercase, and should contain only RNA (resp. DNA) alphabet depending - on what energy parameter set is used + @see vrna_mfe(), vrna_pbacktrack5() - @see vrna_fold_compound_free(), vrna_fold_compound_comparative(), #vrna_md_t + @param fc fold compound + @param length The length of the subsequence, starting from the 5' end + @param structure A pointer to the character array where the secondary structure in + dot-bracket notation will be written to. (Must have size of at least \$p length + 1) - @param sequence A single sequence, or two concatenated sequences seperated by an '&' character - @param md_p An optional set of model details - @param options The options for DP matrices memory allocation - @return A prefilled vrna_fold_compound_t ready to be used for computations (may be @p NULL on error) + @return The minimum free energy (MFE) for the specified @p length in kcal/mol and + a corresponding secondary structure in dot-bracket notation (stored in @p structure) ### Prototype ```c -vrna_fold_compound_t * vrna_fold_compound(const char *sequence, const vrna_md_t *md_p, unsigned int options); +float vrna_backtrack5(vrna_fold_compound_t *fc, unsigned int length, char *structure); ``` """ -function vrna_fold_compound(sequence, md_p, options) - ccall((:vrna_fold_compound, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Cchar}, Ptr{vrna_md_t}, Cuint), sequence, md_p, options) +function vrna_backtrack5(fc, length, structure) + ccall((:vrna_backtrack5, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Cuint, Ptr{Cchar}), fc, length, structure) end """ - vrna_fold_compound_comparative(sequences, md_p, options) - - @brief Retrieve a #vrna_fold_compound_t data structure for sequence alignments + vrna_backtrack_window(fc, Lfold_filename, file_pos, structure, mfe) - This function provides an easy interface to obtain a prefilled #vrna_fold_compound_t by passing an - alignment of sequences. - The optional parameter @p 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 @p options may be used to specify dynamic programming (DP) matrix requirements. +### Prototype +```c +int vrna_backtrack_window(vrna_fold_compound_t *fc, const char *Lfold_filename, long file_pos, char **structure, double mfe); +``` +""" +function vrna_backtrack_window(fc, Lfold_filename, file_pos, structure, mfe) + ccall((:vrna_backtrack_window, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Clong, Ptr{Ptr{Cchar}}, Cdouble), fc, Lfold_filename, file_pos, structure, mfe) +end - #### Options #### - * #VRNA_OPTION_DEFAULT - @copybrief #VRNA_OPTION_DEFAULT - * #VRNA_OPTION_MFE - @copybrief #VRNA_OPTION_MFE - * #VRNA_OPTION_PF - @copybrief #VRNA_OPTION_PF - * #VRNA_OPTION_WINDOW - @copybrief #VRNA_OPTION_WINDOW +# typedef void ( * vrna_mfe_window_f ) ( int start , int end , const char * structure , float en , void * data ) +""" + @brief The default callback for sliding window MFE structure predictions - The above options may be OR-ed together. + @callback + @parblock + This function will be called for each hit in a sliding window MFE prediction. + @endparblock - If you just need the folding compound serving as a container for your data, you can simply pass - #VRNA_OPTION_DEFAULT to the @p 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 vrna_mfe_window() - @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. + @param start provides the first position of the hit (1-based, relative to entire sequence/alignment) + @param end provides the last position of the hit (1-based, relative to the entire sequence/alignment) + @param structure provides the (sub)structure in dot-bracket notation + @param en is the free energy of the structure hit in kcal/mol + @param data is some arbitrary data pointer passed through by the function executing the callback +""" +const vrna_mfe_window_f = Ptr{Cvoid} - @see vrna_fold_compound_free(), vrna_fold_compound(), #vrna_md_t, #VRNA_OPTION_MFE, #VRNA_OPTION_PF, - #VRNA_OPTION_EVAL_ONLY, read_clustal() +# DEPRECATED +const vrna_mfe_window_callback = Cvoid - @param sequences A sequence alignment including 'gap' characters - @param md_p An optional set of model details - @param options The options for DP matrices memory allocation - @return A prefilled vrna_fold_compound_t ready to be used for computations (may be @p NULL on error) -### Prototype -```c -vrna_fold_compound_t * vrna_fold_compound_comparative(const char **sequences, vrna_md_t *md_p, unsigned int options); -``` """ -function vrna_fold_compound_comparative(sequences, md_p, options) - ccall((:vrna_fold_compound_comparative, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Ptr{Cchar}}, Ptr{vrna_md_t}, Cuint), sequences, md_p, options) -end + vrna_mfe_window(fc, file) -""" - vrna_fold_compound_comparative2(sequences, names, orientation, start, genome_size, md_p, options) + @brief Local MFE prediction using a sliding window approach. + + Computes minimum free energy structures using a sliding window + approach, where base pairs may not span outside the window. + In contrast to vrna_mfe(), where a maximum base pair span + may be set using the #vrna_md_t.max_bp_span attribute and one + globally optimal structure is predicted, this function uses a + sliding window to retrieve all locally optimal structures within + each window. + The size of the sliding window is set in the #vrna_md_t.window_size + attribute, prior to the retrieval of the #vrna_fold_compound_t + using vrna_fold_compound() with option #VRNA_OPTION_WINDOW + + The predicted structures are written on-the-fly, either to + stdout, if a NULL pointer is passed as file parameter, or to + the corresponding filehandle. + @see vrna_fold_compound(), vrna_mfe_window_zscore(), vrna_mfe(), + vrna_Lfold(), vrna_Lfoldz(), + #VRNA_OPTION_WINDOW, #vrna_md_t.max_bp_span, #vrna_md_t.window_size + @param fc The #vrna_fold_compound_t with preallocated memory for the DP matrices + @param file The output file handle where predictions are written to (maybe NULL) ### Prototype ```c -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); +float vrna_mfe_window(vrna_fold_compound_t *fc, FILE *file); ``` """ -function vrna_fold_compound_comparative2(sequences, names, orientation, start, genome_size, md_p, options) - ccall((:vrna_fold_compound_comparative2, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Ptr{Cchar}}, Ptr{Ptr{Cchar}}, Ptr{Cuchar}, Ptr{Culonglong}, Ptr{Culonglong}, Ptr{vrna_md_t}, Cuint), sequences, names, orientation, start, genome_size, md_p, options) +function vrna_mfe_window(fc, file) + ccall((:vrna_mfe_window, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Libc.FILE}), fc, file) end """ - vrna_fold_compound_TwoD(sequence, s1, s2, md_p, options) + vrna_mfe_window_cb(fc, cb, data) ### Prototype ```c -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); +float vrna_mfe_window_cb(vrna_fold_compound_t *fc, vrna_mfe_window_f cb, void *data); ``` """ -function vrna_fold_compound_TwoD(sequence, s1, s2, md_p, options) - ccall((:vrna_fold_compound_TwoD, libRNA), Ptr{vrna_fold_compound_t}, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_md_t}, Cuint), sequence, s1, s2, md_p, options) +function vrna_mfe_window_cb(fc, cb, data) + ccall((:vrna_mfe_window_cb, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, vrna_mfe_window_f, Ptr{Cvoid}), fc, cb, data) end """ - vrna_fold_compound_prepare(fc, options) + vrna_Lfold(string, window_size, file) + @brief Local MFE prediction using a sliding window approach (simplified interface) + This simplified interface to vrna_mfe_window() computes the MFE and locally + optimal secondary structure using default options. Structures are predicted + using a sliding window approach, where base pairs may not span outside the + window. Memory required for dynamic programming (DP) matrices will + be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled + matrices are not available any more for any post-processing. + + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_mfe_window(), + and the data structure #vrna_fold_compound_t instead. + + @see vrna_mfe_window(), vrna_Lfoldz(), vrna_mfe_window_zscore() + + @param string The nucleic acid sequence + @param window_size The window size for locally optimal structures + @param file The output file handle where predictions are written to (if NULL, output is written to stdout) ### Prototype ```c -int vrna_fold_compound_prepare(vrna_fold_compound_t *fc, unsigned int options); +float vrna_Lfold(const char *string, int window_size, FILE *file); ``` """ -function vrna_fold_compound_prepare(fc, options) - ccall((:vrna_fold_compound_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) +function vrna_Lfold(string, window_size, file) + ccall((:vrna_Lfold, libRNA), Cfloat, (Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, window_size, file) end """ - vrna_fold_compound_free(fc) - - @brief Free memory occupied by a #vrna_fold_compound_t + vrna_Lfold_cb(string, window_size, cb, data) - @see vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_mx_mfe_free(), vrna_mx_pf_free() - @param fc The #vrna_fold_compound_t that is to be erased from memory ### Prototype ```c -void vrna_fold_compound_free(vrna_fold_compound_t *fc); +float vrna_Lfold_cb(const char *string, int window_size, vrna_mfe_window_f cb, void *data); ``` """ -function vrna_fold_compound_free(fc) - ccall((:vrna_fold_compound_free, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) +function vrna_Lfold_cb(string, window_size, cb, data) + ccall((:vrna_Lfold_cb, libRNA), Cfloat, (Ptr{Cchar}, Cint, vrna_mfe_window_f, Ptr{Cvoid}), string, window_size, cb, data) end """ - vrna_fold_compound_add_auxdata(fc, data, f) - - @brief 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(). + vrna_aliLfold(alignment, maxdist, fp) - @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. - @see vrna_auxdata_free_f() - @param fc The fold_compound the arbitrary data pointer should be associated with - @param data A pointer to an arbitrary data structure - @param f A pointer to function that free's memory occupied by the arbitrary data (May be NULL) ### Prototype ```c -void vrna_fold_compound_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f); +float vrna_aliLfold(const char **alignment, int maxdist, FILE *fp); ``` """ -function vrna_fold_compound_add_auxdata(fc, data, f) - ccall((:vrna_fold_compound_add_auxdata, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, f) +function vrna_aliLfold(alignment, maxdist, fp) + ccall((:vrna_aliLfold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Cint, Ptr{Libc.FILE}), alignment, maxdist, fp) end """ - vrna_fold_compound_add_callback(fc, f) - - @brief 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. + vrna_aliLfold_cb(alignment, maxdist, cb, data) - @see vrna_recursion_status_f(), #vrna_fold_compound_t, - #VRNA_STATUS_MFE_PRE, #VRNA_STATUS_MFE_POST, #VRNA_STATUS_PF_PRE, #VRNA_STATUS_PF_POST - @param fc The fold_compound the callback function should be attached to - @param f The pointer to the recursion status callback function ### Prototype ```c -void vrna_fold_compound_add_callback(vrna_fold_compound_t *fc, vrna_recursion_status_f f); +float vrna_aliLfold_cb(const char **alignment, int maxdist, vrna_mfe_window_f cb, void *data); ``` """ -function vrna_fold_compound_add_callback(fc, f) - ccall((:vrna_fold_compound_add_callback, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_recursion_status_f), fc, f) +function vrna_aliLfold_cb(alignment, maxdist, cb, data) + ccall((:vrna_aliLfold_cb, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Cint, vrna_mfe_window_f, Ptr{Cvoid}), alignment, maxdist, cb, data) end -# typedef void ( * vrna_heat_capacity_f ) ( float temp , float heat_capacity , void * data ) """ - @brief The callback for heat capacity predictions + vrna_params_load(fname, options) - @callback - @parblock - This function will be called for each evaluated temperature in the heat capacity prediction. - @endparblock + @brief Load energy parameters from a file - @see vrna_heat_capacity_cb() + @see vrna_params_load_from_string(), vrna_params_save(), + vrna_params_load_defaults(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() - @param temp The current temperature this results corresponds to in °C - @param heat_capacity The heat capacity in Kcal/(Mol * K) - @param data Some arbitrary data pointer passed through by the function executing the callback + @param fname The path to the file containing the energy parameters + @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) + @return Non-zero on success, 0 on failure +### Prototype +```c +int vrna_params_load(const char fname[], unsigned int options); +``` """ -const vrna_heat_capacity_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_heat_capacity_callback = Cvoid +function vrna_params_load(fname, options) + ccall((:vrna_params_load, libRNA), Cint, (Ptr{Cchar}, Cuint), fname, options) +end """ - vrna_heat_capacity_s - - @brief A single result from heat capacity computations + vrna_params_save(fname, options) - @see vrna_heat_capacity() -""" -struct vrna_heat_capacity_s - temperature::Cfloat - heat_capacity::Cfloat -end + @brief Save energy parameters to a file -""" - @brief A single result from heat capacity computations + @see vrna_params_load() - This is a convenience typedef for #vrna_heat_capacity_s, i.e. results as obtained from vrna_heat_capacity() + @param fname A filename (path) for the file where the current energy parameters will be written to + @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) + @return Non-zero on success, 0 on failure +### Prototype +```c +int vrna_params_save(const char fname[], unsigned int options); +``` """ -const vrna_heat_capacity_t = vrna_heat_capacity_s +function vrna_params_save(fname, options) + ccall((:vrna_params_save, libRNA), Cint, (Ptr{Cchar}, Cuint), fname, options) +end """ - vrna_heat_capacity(fc, T_min, T_max, T_increment, mpoints) - - @brief Compute the specific heat for an RNA + vrna_params_load_from_string(string, name, options) - This function computes an RNAs specific heat in a given temperature range - from the partition function by numeric differentiation. The result is returned - as a list of pairs of temperature in °C and specific heat in Kcal/(Mol*K). + @brief Load energy paramters from string - Users can specify the temperature range for the computation from @p T_min to - @p T_max, as well as the increment step size @p T_increment. The latter also determines - how many times the partition function is computed. Finally, the parameter @p mpoints - determines how smooth the curve should be. The algorithm itself fits a parabola - to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this - parameter produces a smoother curve. + The string must follow the default energy parameter file convention! + The optional @p name argument allows one to specify a name for the + parameter set which is stored internally. - @see vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s + @see vrna_params_load(), vrna_params_save(), + vrna_params_load_defaults(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() - @param fc The #vrna_fold_compound_t with the RNA sequence to analyze - @param T_min Lowest temperature in °C - @param T_max Highest temperature in °C - @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) - @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) - @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. - The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min + @param string A 0-terminated string containing energy parameters + @param name A name for the parameter set in @p string (Maybe @p NULL) + @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) + @return Non-zero on success, 0 on failure ### Prototype ```c -vrna_heat_capacity_t * vrna_heat_capacity(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints); +int vrna_params_load_from_string(const char *string, const char *name, unsigned int options); ``` """ -function vrna_heat_capacity(fc, T_min, T_max, T_increment, mpoints) - ccall((:vrna_heat_capacity, libRNA), Ptr{vrna_heat_capacity_t}, (Ptr{vrna_fold_compound_t}, Cfloat, Cfloat, Cfloat, Cuint), fc, T_min, T_max, T_increment, mpoints) +function vrna_params_load_from_string(string, name, options) + ccall((:vrna_params_load_from_string, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}, Cuint), string, name, options) end """ - vrna_heat_capacity_cb(fc, T_min, T_max, T_increment, mpoints, cb, data) - - @brief Compute the specific heat for an RNA (callback variant) + vrna_params_load_defaults() - Similar to vrna_heat_capacity(), this function computes an RNAs specific heat in - a given temperature range from the partition function by numeric differentiation. - Instead of returning a list of temperature/specific heat pairs, however, this - function returns the individual results through a callback mechanism. The provided - function will be called for each result and passed the corresponding temperature - and specific heat values along with the arbitrary data as provided through the - @p data pointer argument. + @brief Load default RNA energy parameter set - Users can specify the temperature range for the computation from @p T_min to - @p T_max, as well as the increment step size @p T_increment. The latter also determines - how many times the partition function is computed. Finally, the parameter @p mpoints - determines how smooth the curve should be. The algorithm itself fits a parabola - to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this - parameter produces a smoother curve. + This is a convenience function to load the Turner 2004 RNA free + energy parameters. It's the same as calling vrna_params_load_RNA_Turner2004() - @see vrna_heat_capacity(), vrna_heat_capacity_f + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() - @param fc The #vrna_fold_compound_t with the RNA sequence to analyze - @param T_min Lowest temperature in °C - @param T_max Highest temperature in °C - @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) - @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) - @param cb The user-defined callback function that receives the individual results - @param data An arbitrary data structure that will be passed to the callback in conjunction with the results - @return Returns 0 upon failure, and non-zero otherwise + @return Non-zero on success, 0 on failure ### Prototype ```c -int vrna_heat_capacity_cb(vrna_fold_compound_t *fc, float T_min, float T_max, float T_increment, unsigned int mpoints, vrna_heat_capacity_f cb, void *data); +int vrna_params_load_defaults(void); ``` """ -function vrna_heat_capacity_cb(fc, T_min, T_max, T_increment, mpoints, cb, data) - ccall((:vrna_heat_capacity_cb, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cfloat, Cfloat, Cfloat, Cuint, vrna_heat_capacity_f, Ptr{Cvoid}), fc, T_min, T_max, T_increment, mpoints, cb, data) +function vrna_params_load_defaults() + ccall((:vrna_params_load_defaults, libRNA), Cint, ()) end """ - vrna_heat_capacity_simple(sequence, T_min, T_max, T_increment, mpoints) - - @brief Compute the specific heat for an RNA (simplified variant) + vrna_params_load_RNA_Turner2004() - Similar to vrna_heat_capacity(), this function computes an RNAs specific heat - in a given temperature range from the partition function by numeric differentiation. - This simplified version, however, only requires the RNA sequence as input instead of - a vrna_fold_compound_t data structure. The result is returned as a list of pairs of - temperature in °C and specific heat in Kcal/(Mol*K). + @brief Load Turner 2004 RNA energy parameter set - Users can specify the temperature range for the computation from @p T_min to - @p T_max, as well as the increment step size @p T_increment. The latter also determines - how many times the partition function is computed. Finally, the parameter @p mpoints - determines how smooth the curve should be. The algorithm itself fits a parabola - to @f\$ 2 \\cdot mpoints + 1 @f\$ data points to calculate 2nd derivatives. Increasing this - parameter produces a smoother curve. + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of RNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. - @see vrna_heat_capacity(), vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_defaults(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() - @param sequence The RNA sequence input (must be uppercase) - @param T_min Lowest temperature in °C - @param T_max Highest temperature in °C - @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) - @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) - @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. - The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min + @return Non-zero on success, 0 on failure ### Prototype ```c -vrna_heat_capacity_t * vrna_heat_capacity_simple(const char *sequence, float T_min, float T_max, float T_increment, unsigned int mpoints); +int vrna_params_load_RNA_Turner2004(void); ``` """ -function vrna_heat_capacity_simple(sequence, T_min, T_max, T_increment, mpoints) - ccall((:vrna_heat_capacity_simple, libRNA), Ptr{vrna_heat_capacity_t}, (Ptr{Cchar}, Cfloat, Cfloat, Cfloat, Cuint), sequence, T_min, T_max, T_increment, mpoints) +function vrna_params_load_RNA_Turner2004() + ccall((:vrna_params_load_RNA_Turner2004, libRNA), Cint, ()) end """ - inverse_fold(start, target) + vrna_params_load_RNA_Turner1999() - \\brief Find sequences with predefined structure - - This function searches for a sequence with minimum free energy structure - provided in the parameter 'target', starting with sequence 'start'. - It returns 0 if the search was successful, otherwise a structure distance - in terms of the energy difference between the search result and the actual - target 'target' is returned. The found sequence is returned in 'start'. - If #give_up is set to 1, the function will return as soon as it is - clear that the search will be unsuccessful, this speeds up the algorithm - if you are only interested in exact solutions. - - \\param start The start sequence - \\param target The target secondary structure in dot-bracket notation - \\return The distance to the target in case a search was unsuccessful, 0 otherwise -### Prototype -```c -float inverse_fold( char *start, const char *target); -``` -""" -function inverse_fold(start, target) - ccall((:inverse_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), start, target) -end + @brief Load Turner 1999 RNA energy parameter set -""" - inverse_pf_fold(start, target) + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of RNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. - \\brief Find sequence that maximizes probability of a predefined structure + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_defaults(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() - This function searches for a sequence with maximum probability to fold into - the provided structure 'target' using the partition function algorithm. - It returns \\f\$-kT \\cdot \\log(p)\\f\$ where \\f\$p\\f\$ is the frequency of 'target' in - the ensemble of possible structures. This is usually much slower than - inverse_fold(). - \\param start The start sequence - \\param target The target secondary structure in dot-bracket notation - \\return The distance to the target in case a search was unsuccessful, 0 otherwise + @return Non-zero on success, 0 on failure ### Prototype ```c -float inverse_pf_fold(char *start, const char *target); +int vrna_params_load_RNA_Turner1999(void); ``` """ -function inverse_pf_fold(start, target) - ccall((:inverse_pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), start, target) +function vrna_params_load_RNA_Turner1999() + ccall((:vrna_params_load_RNA_Turner1999, libRNA), Cint, ()) end -# typedef void ( * vrna_move_update_f ) ( vrna_fold_compound_t * fc , vrna_move_t neighbor , unsigned int state , void * data ) -""" - @brief Prototype of the neighborhood update callback - - @see vrna_move_neighbor_diff_cb(), #VRNA_NEIGHBOR_CHANGE, #VRNA_NEIGHBOR_INVALID, #VRNA_NEIGHBOR_NEW - - @param fc The fold compound the calling function is working on - @param neighbor The move that generates the (changed or new) neighbor - @param state The state of the neighbor (move) as supplied by argument @p neighbor - @param data Some arbitrary data pointer as passed to vrna_move_neighbor_diff_cb() """ -const vrna_move_update_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_callback_move_update = Cvoid + vrna_params_load_RNA_Andronescu2007() -""" - vrna_loopidx_update(loopidx, pt, length, m) + @brief Load Andronsecu 2007 RNA energy parameter set -@brief Alters the loopIndices array that was constructed with vrna_loopidx_from_ptable(). + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of RNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. -The loopIndex of the current move will be inserted. -The correctness of the input will not be checked because the speed should be optimized. + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_defaults(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() -@param[in,out] loopidx The loop index data structure that needs an update -@param[in] pt A pair table on which the move will be executed -@param length The length of the structure -@param[in] m The move that is applied to the current structure + @return Non-zero on success, 0 on failure ### Prototype ```c -void vrna_loopidx_update(int *loopidx, const short *pt, int length, const vrna_move_t *m); +int vrna_params_load_RNA_Andronescu2007(void); ``` """ -function vrna_loopidx_update(loopidx, pt, length, m) - ccall((:vrna_loopidx_update, libRNA), Cvoid, (Ptr{Cint}, Ptr{Cshort}, Cint, Ptr{vrna_move_t}), loopidx, pt, length, m) +function vrna_params_load_RNA_Andronescu2007() + ccall((:vrna_params_load_RNA_Andronescu2007, libRNA), Cint, ()) end """ - vrna_neighbors(fc, pt, options) + vrna_params_load_RNA_Langdon2018() -@brief Generate neighbors of a secondary structure + @brief Load Langdon 2018 RNA energy parameter set -This function allows one to generate all structural neighbors (according to a particular move set) -of an RNA secondary structure. The neighborhood is then returned as a list of transitions / moves -required to transform the current structure into the actual neighbor. + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of RNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. -@see vrna_neighbors_successive(), vrna_move_apply(), - #VRNA_MOVESET_INSERTION, #VRNA_MOVESET_DELETION, #VRNA_MOVESET_SHIFT, #VRNA_MOVESET_DEFAULT + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_defaults(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() -@param[in] fc A vrna_fold_compound_t containing the energy parameters and model details -@param[in] pt The pair table representation of the structure -@param options Options to modify the behavior of this function, e.g. available move set -@return Neighbors as a list of moves / transitions (the last element in the list has both of its fields set to 0) + @return Non-zero on success, 0 on failure ### Prototype ```c -vrna_move_t * vrna_neighbors(vrna_fold_compound_t *fc, const short *pt, unsigned int options); +int vrna_params_load_RNA_Langdon2018(void); ``` """ -function vrna_neighbors(fc, pt, options) - ccall((:vrna_neighbors, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, Cuint), fc, pt, options) +function vrna_params_load_RNA_Langdon2018() + ccall((:vrna_params_load_RNA_Langdon2018, libRNA), Cint, ()) end """ - vrna_neighbors_successive(fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) + vrna_params_load_RNA_misc_special_hairpins() -@brief Generate neighbors of a secondary structure (the fast way) + @brief Load Misc Special Hairpin RNA energy parameter set -This function implements a fast way to generate all neighbors of a secondary structure -that results from successive applications of individual moves. The speed-up results from -updating an already known list of valid neighbors before the individual move towards the -current structure took place. In essence, this function removes neighbors that are not -accessible anymore and inserts neighbors emerging after a move took place. + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of RNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. -@see vrna_neighbors(), vrna_move_apply(), - #VRNA_MOVESET_INSERTION, #VRNA_MOVESET_DELETION, #VRNA_MOVESET_SHIFT, #VRNA_MOVESET_DEFAULT + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_defaults(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() -@param[in] fc A vrna_fold_compound_t containing the energy parameters and model details -@param[in] curr_move The move that was/will be applied to @p prev_pt -@param[in] prev_pt A pair table representation of the structure before @p curr_move is/was applied -@param[in] prev_neighbors The list of neighbors of @p prev_pt -@param size_prev_neighbors The size of @p prev_neighbors, i.e. the lists length -@param[out] size_neighbors A pointer to store the size / length of the new neighbor list -@param options Options to modify the behavior of this function, e.g. available move set -@return Neighbors as a list of moves / transitions (the last element in the list has both of its fields set to 0) + + @return Non-zero on success, 0 on failure ### Prototype ```c -vrna_move_t * vrna_neighbors_successive(const vrna_fold_compound_t *fc, const vrna_move_t *curr_move, const short *prev_pt, const vrna_move_t *prev_neighbors, int size_prev_neighbors, int *size_neighbors, unsigned int options); +int vrna_params_load_RNA_misc_special_hairpins(void); ``` """ -function vrna_neighbors_successive(fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) - ccall((:vrna_neighbors_successive, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{vrna_move_t}, Ptr{Cshort}, Ptr{vrna_move_t}, Cint, Ptr{Cint}, Cuint), fc, curr_move, prev_pt, prev_neighbors, size_prev_neighbors, size_neighbors, options) +function vrna_params_load_RNA_misc_special_hairpins() + ccall((:vrna_params_load_RNA_misc_special_hairpins, libRNA), Cint, ()) end """ - vrna_move_neighbor_diff_cb(fc, ptable, move, cb, data, options) - - @brief Apply a move to a secondary structure and indicate which neighbors have changed consequentially - - This function applies a move to a secondary structure and explores the local neighborhood of the - affected loop. Any changes to previously compatible neighbors that have been affected by this loop - will be reported through a callback function. In particular, any of the three cases might appear: - - A previously available neighbor move has changed, usually the free energy change of the move (#VRNA_NEIGHBOR_CHANGE) - - A previously available neighbor move became invalid (#VRNA_NEIGHBOR_INVALID) - - A new neighbor move becomes available (#VRNA_NEIGHBOR_NEW) - - @see vrna_move_neighbor_diff(), #VRNA_NEIGHBOR_CHANGE, #VRNA_NEIGHBOR_INVALID, #VRNA_NEIGHBOR_NEW, - #vrna_move_update_f, #VRNA_MOVE_NO_APPLY + vrna_params_load_DNA_Mathews2004() - @param fc A fold compound for the RNA sequence(s) that this function operates on - @param ptable The current structure as pair table - @param move The move to apply - @param cb The address of the callback function that is passed the neighborhood changes - @param data An arbitrary data pointer that will be passed through to the callback function @p cb - @param options Options to modify the behavior of this function, .e.g available move set - @return Non-zero on success, 0 otherwise -### Prototype -```c -int vrna_move_neighbor_diff_cb(vrna_fold_compound_t *fc, short *ptable, vrna_move_t move, vrna_move_update_f cb, void *data, unsigned int options); -``` -""" -function vrna_move_neighbor_diff_cb(fc, ptable, move, cb, data, options) - ccall((:vrna_move_neighbor_diff_cb, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, vrna_move_t, vrna_move_update_f, Ptr{Cvoid}, Cuint), fc, ptable, move, cb, data, options) -end + @brief Load Mathews 2004 DNA energy parameter set -""" - vrna_move_neighbor_diff(fc, ptable, move, invalid_moves, options) + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of DNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. - @brief Apply a move to a secondary structure and indicate which neighbors have changed consequentially + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_defaults(), vrna_params_load_DNA_Mathews1999() - Similar to vrna_move_neighbor_diff_cb(), this function applies a move to a secondary structure and - reports back the neighbors of the current structure become affected by this move. Instead of executing - a callback for each of the affected neighbors, this function compiles two lists of neighbor moves, one - that is returned and consists of all moves that are novel or may have changed in energy, and a second, - @p invalid_moves, that consists of all the neighbor moves that become invalid, respectively. - @param fc A fold compound for the RNA sequence(s) that this function operates on - @param ptable The current structure as pair table - @param move The move to apply - @param invalid_moves The address of a move list where the function stores those moves that become invalid - @param options Options to modify the behavior of this function, .e.g available move set - @return A list of moves that might have changed in energy or are novel compared to the structure before application of the move + @return Non-zero on success, 0 on failure ### Prototype ```c -vrna_move_t * vrna_move_neighbor_diff(vrna_fold_compound_t *fc, short *ptable, vrna_move_t move, vrna_move_t **invalid_moves, unsigned int options); +int vrna_params_load_DNA_Mathews2004(void); ``` """ -function vrna_move_neighbor_diff(fc, ptable, move, invalid_moves, options) - ccall((:vrna_move_neighbor_diff, libRNA), Ptr{vrna_move_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cshort}, vrna_move_t, Ptr{Ptr{vrna_move_t}}, Cuint), fc, ptable, move, invalid_moves, options) +function vrna_params_load_DNA_Mathews2004() + ccall((:vrna_params_load_DNA_Mathews2004, libRNA), Cint, ()) end """ - vrna_MEA(fc, gamma, mea) - - @brief Compute a MEA (maximum expected accuracy) structure - - The algorithm maximizes the expected accuracy + vrna_params_load_DNA_Mathews1999() - @f[ - A(S) = \\sum_{(i,j) \\in S} 2 \\gamma p_{ij} + \\sum_{i \\notin S} p^u_i - @f] + @brief Load Mathews 1999 DNA energy parameter set - Higher values of @f\$\\gamma@f\$ result in more base pairs of lower - probability and thus higher sensitivity. Low values of @f\$\\gamma@f\$ result in structures - containing only highly likely pairs (high specificity). - The code of the MEA function also demonstrates the use of sparse dynamic - programming scheme to reduce the time and memory complexity of folding. + @warning This function also resets the default geometric parameters + as stored in #vrna_md_t to those of DNA. Only subsequently + initialized #vrna_md_t structures will be affected by this + change. - @pre vrna_pf() must be executed on input parameter @p fc + @see vrna_params_load(), vrna_params_load_from_string(), + vrna_params_save(), vrna_params_load_RNA_Turner2004(), + vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), + vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), + vrna_params_load_DNA_Mathews2004(), vrna_params_load_defaults() - @ingroup mea_fold - @param fc The fold compound data structure with pre-filled base pair probability matrix - @param gamma The weighting factor for base pairs vs. unpaired nucleotides - @param mea A pointer to a variable where the MEA value will be written to - @return An MEA structure (or NULL on any error) + @return Non-zero on success, 0 on failure ### Prototype ```c -char * vrna_MEA(vrna_fold_compound_t *fc, double gamma, float *mea); +int vrna_params_load_DNA_Mathews1999(void); ``` """ -function vrna_MEA(fc, gamma, mea) - ccall((:vrna_MEA, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cdouble, Ptr{Cfloat}), fc, gamma, mea) +function vrna_params_load_DNA_Mathews1999() + ccall((:vrna_params_load_DNA_Mathews1999, libRNA), Cint, ()) end """ - vrna_MEA_from_plist(plist_, sequence, gamma, md, mea) + parset - @brief Compute a MEA (maximum expected accuracy) structure from a list of probabilities - - The algorithm maximizes the expected accuracy - - @f[ - A(S) = \\sum_{(i,j) \\in S} 2 \\gamma p_{ij} + \\sum_{i \\notin S} p^u_i - @f] - - Higher values of @f\$\\gamma@f\$ result in more base pairs of lower - probability and thus higher sensitivity. Low values of @f\$\\gamma@f\$ result in structures - containing only highly likely pairs (high specificity). - The code of the MEA function also demonstrates the use of sparse dynamic - programming scheme to reduce the time and memory complexity of folding. + @brief +""" +@cenum parset::Int32 begin + UNKNOWN = -1 + QUIT = 0 + S = 1 + S_H = 2 + HP = 3 + HP_H = 4 + B = 5 + B_H = 6 + IL = 7 + IL_H = 8 + MMH = 9 + MMH_H = 10 + MMI = 11 + MMI_H = 12 + MMI1N = 13 + MMI1N_H = 14 + MMI23 = 15 + MMI23_H = 16 + MMM = 17 + MMM_H = 18 + MME = 19 + MME_H = 20 + D5 = 21 + D5_H = 22 + D3 = 23 + D3_H = 24 + INT11 = 25 + INT11_H = 26 + INT21 = 27 + INT21_H = 28 + INT22 = 29 + INT22_H = 30 + ML = 31 + TL = 32 + TRI = 33 + HEX = 34 + NIN = 35 + MISC = 36 +end - @note The unpaired probabilities @f\$p^u_i = 1 - \\sum_{j \\neq i} p_{ij}@f\$ are usually - computed from the supplied pairing probabilities @f\$p_{ij}@f\$ as stored in @p plist - entries of type #VRNA_PLIST_TYPE_BASEPAIR. To overwrite individual @f\$p^u_o@f\$ - values simply add entries with type #VRNA_PLIST_TYPE_UNPAIRED
- To include G-Quadruplex support, the corresponding field in @p md must be set. +""" + last_parameter_file() - @ingroup mea_fold + @brief Get the file name of the parameter file that was most recently loaded - @param plist A list of base pair probabilities the MEA structure is computed from - @param sequence The RNA sequence that corresponds to the list of probability values - @param gamma The weighting factor for base pairs vs. unpaired nucleotides - @param md A model details data structure (maybe NULL) - @param mea A pointer to a variable where the MEA value will be written to - @return An MEA structure (or NULL on any error) + @return The file name of the last parameter file, or NULL if parameters are still at defaults ### Prototype ```c -char * vrna_MEA_from_plist(vrna_ep_t *plist, const char *sequence, double gamma, vrna_md_t *md, float *mea); +const char * last_parameter_file(void); ``` """ -function vrna_MEA_from_plist(plist_, sequence, gamma, md, mea) - ccall((:vrna_MEA_from_plist, libRNA), Ptr{Cchar}, (Ptr{vrna_ep_t}, Ptr{Cchar}, Cdouble, Ptr{vrna_md_t}, Ptr{Cfloat}), plist_, sequence, gamma, md, mea) +function last_parameter_file() + ccall((:last_parameter_file, libRNA), Ptr{Cchar}, ()) end """ - MEA(p, structure, gamma) + read_parameter_file(fname) ### Prototype @@ -7963,12 +7847,12 @@ end ; ``` """ -function MEA(p, structure, gamma) - ccall((:MEA, libRNA), Cfloat, (Ptr{plist}, Ptr{Cchar}, Cdouble), p, structure, gamma) +function read_parameter_file(fname) + ccall((:read_parameter_file, libRNA), Cvoid, (Ptr{Cchar},), fname) end """ - MEA_seq(p, sequence, structure, gamma, pf) + write_parameter_file(fname) ### Prototype @@ -7976,187 +7860,148 @@ end ; ``` """ -function MEA_seq(p, sequence, structure, gamma, pf) - ccall((:MEA_seq, libRNA), Cfloat, (Ptr{plist}, Ptr{Cchar}, Ptr{Cchar}, Cdouble, Ptr{vrna_exp_param_t}), p, sequence, structure, gamma, pf) +function write_parameter_file(fname) + ccall((:write_parameter_file, libRNA), Cvoid, (Ptr{Cchar},), fname) end """ - vrna_mfe(fc, structure) - - @brief Compute minimum free energy and an appropriate secondary - structure of an RNA sequence, or RNA sequence alignment - - Depending on the type of the provided #vrna_fold_compound_t, this function - predicts the MFE for a single sequence (or connected component of multiple - sequences), or an averaged MFE for a sequence alignment. - If backtracking is activated, it also constructs the corresponding secondary - structure, or consensus structure. - Therefore, the second parameter, @a structure, has to point to an allocated - block of memory with a size of at least @f\$\\mathrm{strlen}(\\mathrm{sequence})+1@f\$ to - store the backtracked MFE structure. (For consensus structures, this is the length of - the alignment + 1. If @p NULL is passed, no backtracking will be performed. - - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - - @see #vrna_fold_compound_t, vrna_fold_compound(), vrna_fold(), vrna_circfold(), - vrna_fold_compound_comparative(), vrna_alifold(), vrna_circalifold() + gettype(ident) - @param fc fold compound - @param structure A pointer to the character array where the - secondary structure in dot-bracket notation will be written to (Maybe NULL) + @brief - @return the minimum free energy (MFE) in kcal/mol ### Prototype ```c -float vrna_mfe(vrna_fold_compound_t *fc, char *structure); +enum parset gettype(const char *ident); ``` """ -function vrna_mfe(fc, structure) - ccall((:vrna_mfe, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function gettype(ident) + ccall((:gettype, libRNA), parset, (Ptr{Cchar},), ident) end """ - vrna_mfe_dimer(fc, structure) + settype(s) + @brief ### Prototype ```c -; +char * settype(enum parset s); ``` """ -function vrna_mfe_dimer(fc, structure) - ccall((:vrna_mfe_dimer, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function settype(s) + ccall((:settype, libRNA), Ptr{Cchar}, (parset,), s) end """ - vrna_fold(sequence, structure) - - @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for an RNA sequence - - This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for an - RNA sequence using default options. Memory required for dynamic programming (DP) matrices will - be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled - matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. - - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_mfe(), - and the data structure #vrna_fold_compound_t instead. - - @see vrna_circfold(), vrna_mfe() + vrna_dimer_pf_s - @param sequence RNA sequence - @param structure A pointer to the character array where the - secondary structure in dot-bracket notation will be written to - @return the minimum free energy (MFE) in kcal/mol -### Prototype -```c -float vrna_fold(const char *sequence, char *structure); -``` + @brief Data structure returned by vrna_pf_dimer() """ -function vrna_fold(sequence, structure) - ccall((:vrna_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +struct vrna_dimer_pf_s + F0AB::Cdouble + FAB::Cdouble + FcAB::Cdouble + FA::Cdouble + FB::Cdouble end """ - vrna_circfold(sequence, structure) + @brief Typename for the data structure that stores the dimer partition functions, #vrna_dimer_pf_s, as returned by vrna_pf_dimer() + @ingroup pf_cofold +""" +const vrna_dimer_pf_t = vrna_dimer_pf_s - @brief Compute Minimum Free Energy (MFE), and a corresponding secondary structure for a circular RNA sequence +struct vrna_multimer_pf_s + F_connected::Cdouble + F_monomers::Ptr{Cdouble} + num_monomers::Csize_t +end - This simplified interface to vrna_mfe() computes the MFE and, if required, a secondary structure for a - circular RNA sequence using default options. Memory required for dynamic programming (DP) matrices will - be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled - matrices are not available any more for any post-processing, e.g. suboptimal backtracking, etc. +const vrna_multimer_pf_t = vrna_multimer_pf_s - Folding of circular RNA sequences is handled as a post-processing step of the forward - recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. +""" + @brief Backward compatibility typedef for #vrna_dimer_pf_s + @ingroup pf_cofold +""" +const cofoldF = vrna_dimer_pf_s - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_mfe(), - and the data structure #vrna_fold_compound_t instead. +""" + vrna_centroid(fc, dist) - @see vrna_fold(), vrna_mfe() + @brief Get the centroid structure of the ensemble - @param sequence RNA sequence - @param structure A pointer to the character array where the - secondary structure in dot-bracket notation will be written to - @return the minimum free energy (MFE) in kcal/mol + The centroid is the structure with the minimal average distance to all other structures + \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n + Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ + The distance of the centroid to the ensemble is written to the memory adressed by @a dist. + + @ingroup centroid_fold + @param[in] fc The fold compound data structure + @param[out] dist A pointer to the distance variable where the centroid distance will be written to + @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) ### Prototype ```c -float vrna_circfold(const char *sequence, char *structure); +char * vrna_centroid(vrna_fold_compound_t *fc, double *dist); ``` """ -function vrna_circfold(sequence, structure) - ccall((:vrna_circfold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +function vrna_centroid(fc, dist) + ccall((:vrna_centroid, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Ptr{Cdouble}), fc, dist) end """ - vrna_alifold(sequences, structure) - - @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure - for an RNA sequence alignment using a comparative method + vrna_centroid_from_plist(length, dist, pl) - This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary - structure for an RNA sequence alignment using default options. Memory required for dynamic programming - (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of this function, the - recursively filled matrices are not available any more for any post-processing, e.g. suboptimal - backtracking, etc. + @brief Get the centroid structure of the ensemble - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_mfe(), - and the data structure #vrna_fold_compound_t instead. + This function is a threadsafe replacement for @ref centroid() with a #vrna_ep_t input - @see vrna_circalifold(), vrna_mfe() + The centroid is the structure with the minimal average distance to all other structures + \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n + Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ + The distance of the centroid to the ensemble is written to the memory adressed by @a dist. - @param sequences RNA sequence alignment - @param structure A pointer to the character array where the - secondary structure in dot-bracket notation will be written to - @return the minimum free energy (MFE) in kcal/mol + @ingroup centroid_fold + @param[in] length The length of the sequence + @param[out] dist A pointer to the distance variable where the centroid distance will be written to + @param[in] pl A pair list containing base pair probability information about the ensemble + @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) ### Prototype ```c -float vrna_alifold(const char **sequences, char *structure); +char * vrna_centroid_from_plist(int length, double *dist, vrna_ep_t *pl); ``` """ -function vrna_alifold(sequences, structure) - ccall((:vrna_alifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), sequences, structure) +function vrna_centroid_from_plist(length, dist, pl) + ccall((:vrna_centroid_from_plist, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{vrna_ep_t}), length, dist, pl) end """ - vrna_circalifold(sequences, structure) + vrna_centroid_from_probs(length, dist, probs) - @brief Compute Minimum Free Energy (MFE), and a corresponding consensus secondary structure - for a sequence alignment of circular RNAs using a comparative method + @brief Get the centroid structure of the ensemble - This simplified interface to vrna_mfe() computes the MFE and, if required, a consensus secondary - structure for an RNA sequence alignment using default options. Memory required for dynamic programming - (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of this function, the - recursively filled matrices are not available any more for any post-processing, e.g. suboptimal - backtracking, etc. + This function is a threadsafe replacement for @ref centroid() with a probability array input - Folding of circular RNA sequences is handled as a post-processing step of the forward - recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. - - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_mfe(), - and the data structure #vrna_fold_compound_t instead. - - @see vrna_alifold(), vrna_mfe() + The centroid is the structure with the minimal average distance to all other structures + \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n + Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ + The distance of the centroid to the ensemble is written to the memory adressed by @a dist. - @param sequences Sequence alignment of circular RNAs - @param structure A pointer to the character array where the - secondary structure in dot-bracket notation will be written to - @return the minimum free energy (MFE) in kcal/mol + @ingroup centroid_fold + @param[in] length The length of the sequence + @param[out] dist A pointer to the distance variable where the centroid distance will be written to + @param[in] probs An upper triangular matrix containing base pair probabilities (access via iindx @ref vrna_idx_row_wise() ) + @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) ### Prototype ```c -float vrna_circalifold(const char **sequences, char *structure); +char * vrna_centroid_from_probs(int length, double *dist, FLT_OR_DBL *probs); ``` """ -function vrna_circalifold(sequences, structure) - ccall((:vrna_circalifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}), sequences, structure) +function vrna_centroid_from_probs(length, dist, probs) + ccall((:vrna_centroid_from_probs, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{FLT_OR_DBL}), length, dist, probs) end """ - vrna_cofold(sequence, structure) + get_centroid_struct_pl(length, dist, pl) ### Prototype @@ -8164,2064 +8009,2468 @@ end ; ``` """ -function vrna_cofold(sequence, structure) - ccall((:vrna_cofold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +function get_centroid_struct_pl(length, dist, pl) + ccall((:get_centroid_struct_pl, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{vrna_ep_t}), length, dist, pl) end """ - vrna_backtrack_from_intervals(fc, bp_stack, bt_stack, s) + get_centroid_struct_pr(length, dist, pr) + - @brief ### Prototype ```c -int vrna_backtrack_from_intervals(vrna_fold_compound_t *fc, vrna_bp_stack_t *bp_stack, sect bt_stack[], int s); +; ``` """ -function vrna_backtrack_from_intervals(fc, bp_stack, bt_stack, s) - ccall((:vrna_backtrack_from_intervals, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_bp_stack_t}, Ptr{sect}, Cint), fc, bp_stack, bt_stack, s) +function get_centroid_struct_pr(length, dist, pr) + ccall((:get_centroid_struct_pr, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{FLT_OR_DBL}), length, dist, pr) end +# typedef void ( * vrna_bs_result_f ) ( const char * structure , void * data ) """ - vrna_backtrack5(fc, length, structure) - - @brief Backtrack an MFE (sub)structure - - This function allows one to backtrack the MFE structure for a (sub)sequence - - @note On error, the function returns #INF / 100. and stores the empty string - in @p structure. - - @pre Requires pre-filled MFE dynamic programming matrices, i.e. one has to call vrna_mfe() - prior to calling this function + @brief Callback for Boltzmann sampling - @see vrna_mfe(), vrna_pbacktrack5() +@callback +@parblock +This function will be called for each secondary structure that has been successfully backtraced +from the partition function DP matrices. +@endparblock - @param fc fold compound - @param length The length of the subsequence, starting from the 5' end - @param structure A pointer to the character array where the secondary structure in - dot-bracket notation will be written to. (Must have size of at least \$p length + 1) +@see vrna_pbacktrack5_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), + vrna_pbacktrack_resume_cb() - @return The minimum free energy (MFE) for the specified @p length in kcal/mol and - a corresponding secondary structure in dot-bracket notation (stored in @p structure) -### Prototype -```c -float vrna_backtrack5(vrna_fold_compound_t *fc, unsigned int length, char *structure); -``` +@param structure The secondary structure in dot-bracket notation +@param data Some arbitrary, auxiliary data address as provided to the calling function """ -function vrna_backtrack5(fc, length, structure) - ccall((:vrna_backtrack5, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Cuint, Ptr{Cchar}), fc, length, structure) -end +const vrna_bs_result_f = Ptr{Cvoid} -""" - vrna_backtrack_window(fc, Lfold_filename, file_pos, structure, mfe) +# DEPRECATED +const vrna_boltzmann_sampling_callback = Cvoid +mutable struct vrna_pbacktrack_memory_s end -### Prototype -```c -int vrna_backtrack_window(vrna_fold_compound_t *fc, const char *Lfold_filename, long file_pos, char **structure, double mfe); -``` """ -function vrna_backtrack_window(fc, Lfold_filename, file_pos, structure, mfe) - ccall((:vrna_backtrack_window, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Clong, Ptr{Ptr{Cchar}}, Cdouble), fc, Lfold_filename, file_pos, structure, mfe) -end + @brief Boltzmann sampling memory data structure -# typedef void ( * vrna_mfe_window_f ) ( int start , int end , const char * structure , float en , void * data ) -""" - @brief The default callback for sliding window MFE structure predictions + This structure is required for properly resuming a previous sampling round in + specialized Boltzmann sampling, such as non-redundant backtracking. - @callback - @parblock - This function will be called for each hit in a sliding window MFE prediction. - @endparblock + Initialize with @p NULL and pass its address to the corresponding + functions vrna_pbacktrack5_resume(), etc. - @see vrna_mfe_window() + @note Do not forget to release memory occupied by this data structure before + losing its context! Use vrna_pbacktrack_mem_free(). - @param start provides the first position of the hit (1-based, relative to entire sequence/alignment) - @param end provides the last position of the hit (1-based, relative to the entire sequence/alignment) - @param structure provides the (sub)structure in dot-bracket notation - @param en is the free energy of the structure hit in kcal/mol - @param data is some arbitrary data pointer passed through by the function executing the callback + @see vrna_pbacktrack5_resume(), vrna_pbacktrack_resume(), vrna_pbacktrack5_resume_cb(), + vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_free() """ -const vrna_mfe_window_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_mfe_window_callback = Cvoid +const vrna_pbacktrack_mem_t = Ptr{vrna_pbacktrack_memory_s} """ - vrna_mfe_window(fc, file) + vrna_pbacktrack5(fc, length) - @brief Local MFE prediction using a sliding window approach. + @brief Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability - Computes minimum free energy structures using a sliding window - approach, where base pairs may not span outside the window. - In contrast to vrna_mfe(), where a maximum base pair span - may be set using the #vrna_md_t.max_bp_span attribute and one - globally optimal structure is predicted, this function uses a - sliding window to retrieve all locally optimal structures within - each window. - The size of the sliding window is set in the #vrna_md_t.window_size - attribute, prior to the retrieval of the #vrna_fold_compound_t - using vrna_fold_compound() with option #VRNA_OPTION_WINDOW + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a secondary structure. The parameter @p length specifies the length + of the substructure starting from the 5' end. - The predicted structures are written on-the-fly, either to - stdout, if a NULL pointer is passed as file parameter, or to - the corresponding filehandle. + The structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability - @see vrna_fold_compound(), vrna_mfe_window_zscore(), vrna_mfe(), - vrna_Lfold(), vrna_Lfoldz(), - #VRNA_OPTION_WINDOW, #vrna_md_t.max_bp_span, #vrna_md_t.window_size + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] - @param fc The #vrna_fold_compound_t with preallocated memory for the DP matrices - @param file The output file handle where predictions are written to (maybe NULL) -### Prototype -```c -float vrna_mfe_window(vrna_fold_compound_t *fc, FILE *file); -``` -""" -function vrna_mfe_window(fc, file) - ccall((:vrna_mfe_window, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, Ptr{Libc.FILE}), fc, file) -end + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. -""" - vrna_mfe_window_cb(fc, cb, data) + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + @see vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack() + @param fc The fold compound data structure + @param length The length of the subsequence to consider (starting with 5' end) + @return A sampled secondary structure in dot-bracket notation (or NULL on error) ### Prototype ```c -float vrna_mfe_window_cb(vrna_fold_compound_t *fc, vrna_mfe_window_f cb, void *data); +char * vrna_pbacktrack5(vrna_fold_compound_t *fc, unsigned int length); ``` """ -function vrna_mfe_window_cb(fc, cb, data) - ccall((:vrna_mfe_window_cb, libRNA), Cfloat, (Ptr{vrna_fold_compound_t}, vrna_mfe_window_f, Ptr{Cvoid}), fc, cb, data) +function vrna_pbacktrack5(fc, length) + ccall((:vrna_pbacktrack5, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cuint), fc, length) end """ - vrna_Lfold(string, window_size, file) + vrna_pbacktrack5_num(fc, num_samples, length, options) - @brief Local MFE prediction using a sliding window approach (simplified interface) + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - This simplified interface to vrna_mfe_window() computes the MFE and locally - optimal secondary structure using default options. Structures are predicted - using a sliding window approach, where base pairs may not span outside the - window. Memory required for dynamic programming (DP) matrices will - be allocated and free'd on-the-fly. Hence, after return of this function, the recursively filled - matrices are not available any more for any post-processing. + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_mfe_window(), - and the data structure #vrna_fold_compound_t instead. + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability - @see vrna_mfe_window(), vrna_Lfoldz(), vrna_mfe_window_zscore() + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] - @param string The nucleic acid sequence - @param window_size The window size for locally optimal structures - @param file The output file handle where predictions are written to (if NULL, output is written to stdout) -### Prototype -```c -float vrna_Lfold(const char *string, int window_size, FILE *file); -``` -""" -function vrna_Lfold(string, window_size, file) - ccall((:vrna_Lfold, libRNA), Cfloat, (Ptr{Cchar}, Cint, Ptr{Libc.FILE}), string, window_size, file) -end + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. -""" - vrna_Lfold_cb(string, window_size, cb, data) + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices -### Prototype -```c -float vrna_Lfold_cb(const char *string, int window_size, vrna_mfe_window_f cb, void *data); -``` -""" -function vrna_Lfold_cb(string, window_size, cb, data) - ccall((:vrna_Lfold_cb, libRNA), Cfloat, (Ptr{Cchar}, Cint, vrna_mfe_window_f, Ptr{Cvoid}), string, window_size, cb, data) -end + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. -""" - vrna_aliLfold(alignment, maxdist, fp) + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + @see vrna_pbacktrack5(), vrna_pbacktrack5_cb(), vrna_pbacktrack_num(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param length The length of the subsequence to consider (starting with 5' end) + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -float vrna_aliLfold(const char **alignment, int maxdist, FILE *fp); +char ** vrna_pbacktrack5_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, unsigned int options); ``` """ -function vrna_aliLfold(alignment, maxdist, fp) - ccall((:vrna_aliLfold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Cint, Ptr{Libc.FILE}), alignment, maxdist, fp) +function vrna_pbacktrack5_num(fc, num_samples, length, options) + ccall((:vrna_pbacktrack5_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint), fc, num_samples, length, options) end """ - vrna_aliLfold_cb(alignment, maxdist, cb, data) + vrna_pbacktrack5_cb(fc, num_samples, length, cb, data, options) + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability -### Prototype -```c -float vrna_aliLfold_cb(const char **alignment, int maxdist, vrna_mfe_window_f cb, void *data); -``` -""" -function vrna_aliLfold_cb(alignment, maxdist, cb, data) - ccall((:vrna_aliLfold_cb, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Cint, vrna_mfe_window_f, Ptr{Cvoid}), alignment, maxdist, cb, data) -end + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. -""" - vrna_params_load(fname, options) + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability - @brief Load energy parameters from a file + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] - @see vrna_params_load_from_string(), vrna_params_save(), - vrna_params_load_defaults(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. - @param fname The path to the file containing the energy parameters - @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) - @return Non-zero on success, 0 on failure -### Prototype -```c -int vrna_params_load(const char fname[], unsigned int options); -``` -""" -function vrna_params_load(fname, options) - ccall((:vrna_params_load, libRNA), Cint, (Ptr{Cchar}, Cuint), fname, options) -end + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. -""" - vrna_params_save(fname, options) + In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the + structure samples through a callback mechanism. - @brief Save energy parameters to a file + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices - @see vrna_params_load() + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - @param fname A filename (path) for the file where the current energy parameters will be written to - @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) - @return Non-zero on success, 0 on failure + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param length The length of the subsequence to consider (starting with 5' end) + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced ### Prototype ```c -int vrna_params_save(const char fname[], unsigned int options); +unsigned int vrna_pbacktrack5_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, unsigned int options); ``` """ -function vrna_params_save(fname, options) - ccall((:vrna_params_save, libRNA), Cint, (Ptr{Cchar}, Cuint), fname, options) +function vrna_pbacktrack5_cb(fc, num_samples, length, cb, data, options) + ccall((:vrna_pbacktrack5_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, length, cb, data, options) end """ - vrna_params_load_from_string(string, name, options) + vrna_pbacktrack5_resume(fc, num_samples, length, nr_mem, options) - @brief Load energy paramters from string + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - The string must follow the default energy parameter file convention! - The optional @p name argument allows one to specify a name for the - parameter set which is stored internally. + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. - @see vrna_params_load(), vrna_params_save(), - vrna_params_load_defaults(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability - @param string A 0-terminated string containing energy parameters - @param name A name for the parameter set in @p string (Maybe @p NULL) - @param options File format bit-mask (usually #VRNA_PARAMETER_FORMAT_DEFAULT) - @return Non-zero on success, 0 on failure -### Prototype -```c -int vrna_params_load_from_string(const char *string, const char *name, unsigned int options); -``` -""" -function vrna_params_load_from_string(string, name, options) - ccall((:vrna_params_load_from_string, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}, Cuint), string, name, options) -end + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] -""" - vrna_params_load_defaults() + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. - @brief Load default RNA energy parameter set + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. - This is a convenience function to load the Turner 2004 RNA free - energy parameters. It's the same as calling vrna_params_load_RNA_Turner2004() + In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous + sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. + For that purpose, the user passes the address of a Boltzmann sampling data structure + (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each + successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume(). - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; - @return Non-zero on success, 0 on failure -### Prototype -```c -int vrna_params_load_defaults(void); -``` -""" -function vrna_params_load_defaults() - ccall((:vrna_params_load_defaults, libRNA), Cint, ()) -end +// sample the first 100 structures +vrna_pbacktrack5_resume(fc, + 100, + fc->length, + &nonredundant_memory, + options); -""" - vrna_params_load_RNA_Turner2004() +// sample another 500 structures +vrna_pbacktrack5_resume(fc, + 500, + fc->length, + &nonredundant_memory, + options); - @brief Load Turner 2004 RNA energy parameter set +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of RNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_defaults(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - @return Non-zero on success, 0 on failure + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param length The length of the subsequence to consider (starting with 5' end) + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -int vrna_params_load_RNA_Turner2004(void); +char ** vrna_pbacktrack5_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); ``` """ -function vrna_params_load_RNA_Turner2004() - ccall((:vrna_params_load_RNA_Turner2004, libRNA), Cint, ()) +function vrna_pbacktrack5_resume(fc, num_samples, length, nr_mem, options) + ccall((:vrna_pbacktrack5_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, length, nr_mem, options) end """ - vrna_params_load_RNA_Turner1999() - - @brief Load Turner 1999 RNA energy parameter set + vrna_pbacktrack5_resume_cb(fc, num_samples, length, cb, data, nr_mem, options) - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of RNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_defaults(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability - @return Non-zero on success, 0 on failure -### Prototype -```c -int vrna_params_load_RNA_Turner1999(void); -``` -""" -function vrna_params_load_RNA_Turner1999() - ccall((:vrna_params_load_RNA_Turner1999, libRNA), Cint, ()) -end + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] -""" - vrna_params_load_RNA_Andronescu2007() + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. - @brief Load Andronsecu 2007 RNA energy parameter set + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of RNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + In contrast to vrna_pbacktrack5_resume() this function yields the structure samples + through a callback mechanism. - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_defaults(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; - @return Non-zero on success, 0 on failure -### Prototype -```c -int vrna_params_load_RNA_Andronescu2007(void); -``` -""" -function vrna_params_load_RNA_Andronescu2007() - ccall((:vrna_params_load_RNA_Andronescu2007, libRNA), Cint, ()) -end +// sample the first 100 structures +vrna_pbacktrack5_resume_cb(fc, + 100, + fc->length, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); -""" - vrna_params_load_RNA_Langdon2018() +// sample another 500 structures +vrna_pbacktrack5_resume_cb(fc, + 500, + fc->length, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); - @brief Load Langdon 2018 RNA energy parameter set +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of RNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_defaults(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - @return Non-zero on success, 0 on failure + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param length The length of the subsequence to consider (starting with 5' end) + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced ### Prototype ```c -int vrna_params_load_RNA_Langdon2018(void); +unsigned int vrna_pbacktrack5_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); ``` """ -function vrna_params_load_RNA_Langdon2018() - ccall((:vrna_params_load_RNA_Langdon2018, libRNA), Cint, ()) +function vrna_pbacktrack5_resume_cb(fc, num_samples, length, cb, data, nr_mem, options) + ccall((:vrna_pbacktrack5_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, length, cb, data, nr_mem, options) end """ - vrna_params_load_RNA_misc_special_hairpins() + vrna_pbacktrack(fc) - @brief Load Misc Special Hairpin RNA energy parameter set + @brief Sample a secondary structure from the Boltzmann ensemble according its probability - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of RNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a secondary structure. - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_defaults(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_DNA_Mathews1999() + The structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. - @return Non-zero on success, 0 on failure + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @see vrna_pbacktrack5(), vrna_pbacktrack_num, vrna_pbacktrack_cb() + + @param fc The fold compound data structure + @return A sampled secondary structure in dot-bracket notation (or NULL on error) ### Prototype ```c -int vrna_params_load_RNA_misc_special_hairpins(void); +char * vrna_pbacktrack(vrna_fold_compound_t *fc); ``` """ -function vrna_params_load_RNA_misc_special_hairpins() - ccall((:vrna_params_load_RNA_misc_special_hairpins, libRNA), Cint, ()) +function vrna_pbacktrack(fc) + ccall((:vrna_pbacktrack, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_params_load_DNA_Mathews2004() + vrna_pbacktrack_num(fc, num_samples, options) - @brief Load Mathews 2004 DNA energy parameter set + @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of DNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_defaults(), vrna_params_load_DNA_Mathews1999() + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] - @return Non-zero on success, 0 on failure + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack(), vrna_pbacktrack_cb(), vrna_pbacktrack5_num(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -int vrna_params_load_DNA_Mathews2004(void); +char ** vrna_pbacktrack_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int options); ``` """ -function vrna_params_load_DNA_Mathews2004() - ccall((:vrna_params_load_DNA_Mathews2004, libRNA), Cint, ()) +function vrna_pbacktrack_num(fc, num_samples, options) + ccall((:vrna_pbacktrack_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, num_samples, options) end """ - vrna_params_load_DNA_Mathews1999() + vrna_pbacktrack_cb(fc, num_samples, cb, data, options) - @brief Load Mathews 1999 DNA energy parameter set + @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability - @warning This function also resets the default geometric parameters - as stored in #vrna_md_t to those of DNA. Only subsequently - initialized #vrna_md_t structures will be affected by this - change. + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. - @see vrna_params_load(), vrna_params_load_from_string(), - vrna_params_save(), vrna_params_load_RNA_Turner2004(), - vrna_params_load_RNA_Turner1999(), vrna_params_load_RNA_Andronescu2007(), - vrna_params_load_RNA_Langdon2018(), vrna_params_load_RNA_misc_special_hairpins(), - vrna_params_load_DNA_Mathews2004(), vrna_params_load_defaults() + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] - @return Non-zero on success, 0 on failure + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + In contrast to vrna_pbacktrack() and vrna_pbacktrack_num() this function yields the + structure samples through a callback mechanism. + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack(), vrna_pbacktrack_num(), vrna_pbacktrack5_cb(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced ### Prototype ```c -int vrna_params_load_DNA_Mathews1999(void); +unsigned int vrna_pbacktrack_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, unsigned int options); ``` """ -function vrna_params_load_DNA_Mathews1999() - ccall((:vrna_params_load_DNA_Mathews1999, libRNA), Cint, ()) +function vrna_pbacktrack_cb(fc, num_samples, cb, data, options) + ccall((:vrna_pbacktrack_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, cb, data, options) end """ - parset + vrna_pbacktrack_resume(fc, num_samples, nr_mem, options) - @brief -""" -@cenum parset::Int32 begin - UNKNOWN = -1 - QUIT = 0 - S = 1 - S_H = 2 - HP = 3 - HP_H = 4 - B = 5 - B_H = 6 - IL = 7 - IL_H = 8 - MMH = 9 - MMH_H = 10 - MMI = 11 - MMI_H = 12 - MMI1N = 13 - MMI1N_H = 14 - MMI23 = 15 - MMI23_H = 16 - MMM = 17 - MMM_H = 18 - MME = 19 - MME_H = 20 - D5 = 21 - D5_H = 22 - D3 = 23 - D3_H = 24 - INT11 = 25 - INT11_H = 26 - INT21 = 27 - INT21_H = 28 - INT22 = 29 - INT22_H = 30 - ML = 31 - TL = 32 - TRI = 33 - HEX = 34 - NIN = 35 - MISC = 36 + @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability + + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. + + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] + + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + In contrast to vrna_pbacktrack_cb() this function allows for resuming a previous + sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. + For that purpose, the user passes the address of a Boltzmann sampling data structure + (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each + successive call to vrna_pbacktrack_resume_cb() or vrna_pbacktrack_resume(). + + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; + +// sample the first 100 structures +vrna_pbacktrack_resume(fc, + 100, + &nonredundant_memory, + options); + +// sample another 500 structures +vrna_pbacktrack_resume(fc, + 500, + &nonredundant_memory, + options); + +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack_resume_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) +### Prototype +```c +char ** vrna_pbacktrack_resume(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +``` +""" +function vrna_pbacktrack_resume(fc, num_samples, nr_mem, options) + ccall((:vrna_pbacktrack_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, nr_mem, options) +end + +""" + vrna_pbacktrack_resume_cb(fc, num_samples, cb, data, nr_mem, options) + + @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability + + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. + + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] + + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + In contrast to vrna_pbacktrack5_resume() this function yields the structure samples + through a callback mechanism. + + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; + +// sample the first 100 structures +vrna_pbacktrack5_resume_cb(fc, + 100, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); + +// sample another 500 structures +vrna_pbacktrack5_resume_cb(fc, + 500, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); + +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack_resume(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced +### Prototype +```c +unsigned int vrna_pbacktrack_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +``` +""" +function vrna_pbacktrack_resume_cb(fc, num_samples, cb, data, nr_mem, options) + ccall((:vrna_pbacktrack_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, cb, data, nr_mem, options) end -""" - last_parameter_file() +""" + vrna_pbacktrack_sub(fc, start, _end) + + @brief Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability + + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a secondary structure. The parameters @p start and @p end specify the interval + @f\$ [start:end] @f\$ of the subsequence with @f\$ 1 \\leq start < end \\leq n@f\$ for sequence length @f\$ n @f\$, + the structure @f\$ s_{start,end} @f\$ should be drawn from. + + The resulting substructure @f\$ s_{start,end} @f\$ with free energy @f\$ E(s_{start, end}) @f\$ is picked from + the Boltzmann distributed sub ensemble of all structures within the interval @f\$ [start:end] @f\$ according + to its probability + + @f[ + p(s_{start,end}) = \\frac{exp(-E(s_{start,end}) / kT)}{Z_{start,end}} + @f] + + with partition function @f\$ Z_{start,end} = \\sum_{s_{start,end}} exp(-E(s_{start,end}) / kT) @f\$, + Boltzmann constant @f\$ k @f\$ and thermodynamic temperature @f\$ T @f\$. + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @see vrna_pbacktrack_sub_num(), vrna_pbacktrack_sub_cb(), vrna_pbacktrack() + + @param fc The fold compound data structure + @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) + @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) + @return A sampled secondary structure in dot-bracket notation (or NULL on error) +### Prototype +```c +char * vrna_pbacktrack_sub(vrna_fold_compound_t *fc, unsigned int start, unsigned int end); +``` +""" +function vrna_pbacktrack_sub(fc, start, _end) + ccall((:vrna_pbacktrack_sub, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, start, _end) +end + +""" + vrna_pbacktrack_sub_num(fc, num_samples, start, _end, options) + + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. + + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] + + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack_sub(), vrna_pbacktrack_sub_cb(), vrna_pbacktrack_num(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) + @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) +### Prototype +```c +char ** vrna_pbacktrack_sub_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, unsigned int options); +``` +""" +function vrna_pbacktrack_sub_num(fc, num_samples, start, _end, options) + ccall((:vrna_pbacktrack_sub_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Cuint), fc, num_samples, start, _end, options) +end + +""" + vrna_pbacktrack_sub_cb(fc, num_samples, start, _end, cb, data, options) + + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. + + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] + + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the + structure samples through a callback mechanism. + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - @brief Get the file name of the parameter file that was most recently loaded + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. - @return The file name of the last parameter file, or NULL if parameters are still at defaults + @see vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), + #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) + @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced ### Prototype ```c -const char * last_parameter_file(void); +unsigned int vrna_pbacktrack_sub_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, unsigned int options); ``` """ -function last_parameter_file() - ccall((:last_parameter_file, libRNA), Ptr{Cchar}, ()) +function vrna_pbacktrack_sub_cb(fc, num_samples, start, _end, cb, data, options) + ccall((:vrna_pbacktrack_sub_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, start, _end, cb, data, options) end """ - read_parameter_file(fname) + vrna_pbacktrack_sub_resume(fc, num_samples, start, _end, nr_mem, options) + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability -### Prototype -```c -; -``` -""" -function read_parameter_file(fname) - ccall((:read_parameter_file, libRNA), Cvoid, (Ptr{Cchar},), fname) -end + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. -""" - write_parameter_file(fname) + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] -### Prototype -```c -; -``` -""" -function write_parameter_file(fname) - ccall((:write_parameter_file, libRNA), Cvoid, (Ptr{Cchar},), fname) -end + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. -""" - gettype(ident) + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. - @brief + In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous + sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. + For that purpose, the user passes the address of a Boltzmann sampling data structure + (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each + successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume(). -### Prototype -```c -enum parset gettype(const char *ident); -``` -""" -function gettype(ident) - ccall((:gettype, libRNA), parset, (Ptr{Cchar},), ident) -end + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; -""" - settype(s) +// sample the first 100 structures +vrna_pbacktrack5_resume(fc, + 100, + fc->length, + &nonredundant_memory, + options); - @brief +// sample another 500 structures +vrna_pbacktrack5_resume(fc, + 500, + fc->length, + &nonredundant_memory, + options); + +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) + @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -char * settype(enum parset s); +char ** vrna_pbacktrack_sub_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); ``` """ -function settype(s) - ccall((:settype, libRNA), Ptr{Cchar}, (parset,), s) +function vrna_pbacktrack_sub_resume(fc, num_samples, start, _end, nr_mem, options) + ccall((:vrna_pbacktrack_sub_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, start, _end, nr_mem, options) end """ - vrna_dimer_pf_s + vrna_pbacktrack_sub_resume_cb(fc, num_samples, start, _end, cb, data, nr_mem, options) - @brief Data structure returned by vrna_pf_dimer() -""" -struct vrna_dimer_pf_s - F0AB::Cdouble - FAB::Cdouble - FcAB::Cdouble - FA::Cdouble - FB::Cdouble -end + @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability -""" - @brief Typename for the data structure that stores the dimer partition functions, #vrna_dimer_pf_s, as returned by vrna_pf_dimer() - @ingroup pf_cofold -""" -const vrna_dimer_pf_t = vrna_dimer_pf_s + Perform a probabilistic (stochastic) backtracing in the partition function DP arrays + to obtain a set of @p num_samples secondary structures. The parameter @p length specifies + the length of the substructure starting from the 5' end. -struct vrna_multimer_pf_s - F_connected::Cdouble - F_monomers::Ptr{Cdouble} - num_monomers::Csize_t -end + Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed + ensemble according to its probability -const vrna_multimer_pf_t = vrna_multimer_pf_s + @f[ + p(s) = \\frac{exp(-E(s) / kT)}{Z} + @f] -""" - @brief Backward compatibility typedef for #vrna_dimer_pf_s - @ingroup pf_cofold -""" -const cofoldF = vrna_dimer_pf_s + with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and + thermodynamic temperature @f\$ T @f\$. + + Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing + mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of + @rstinline :cite:t:`michalik:2017` @endrst. + + In contrast to vrna_pbacktrack5_resume() this function yields the structure samples + through a callback mechanism. + + A successive sample call to this function may look like: +@code{.c} +vrna_pbacktrack_mem_t nonredundant_memory = NULL; + +// sample the first 100 structures +vrna_pbacktrack5_resume_cb(fc, + 100, + fc->length, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); + +// sample another 500 structures +vrna_pbacktrack5_resume_cb(fc, + 500, + fc->length, + &callback_function, + (void *)&callback_data, + &nonredundant_memory, + options); + +// release memory occupied by the non-redundant memory data structure +vrna_pbacktrack_mem_free(nonredundant_memory); +@endcode + + @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() + or similar. This can be done easily by passing vrna_fold_compound() a model details parameter + with vrna_md_t.uniq_ML = 1.
+ vrna_pf() has to be called first to fill the partition function matrices + + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + + @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may + not yield the full number of requested samples. This may happen if + a) the number of requested structures is larger than the total number + of structuresin the ensemble, + b) numeric instabilities prevent the backtracking function to enumerate + structures with high free energies, or + c) any other error occurs. + + @see vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), + #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, + vrna_pbacktrack_mem_free + @param fc The fold compound data structure + @param num_samples The size of the sample set, i.e. number of structures + @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) + @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) + @param cb The callback that receives the sampled structure + @param data A data structure passed through to the callback @p cb + @param nr_mem The address of the Boltzmann sampling memory data structure + @param options A bitwise OR-flag indicating the backtracing mode. + @return The number of structures actually backtraced +### Prototype +```c +unsigned int vrna_pbacktrack_sub_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +``` """ - vrna_centroid(fc, dist) +function vrna_pbacktrack_sub_resume_cb(fc, num_samples, start, _end, cb, data, nr_mem, options) + ccall((:vrna_pbacktrack_sub_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, start, _end, cb, data, nr_mem, options) +end - @brief Get the centroid structure of the ensemble +""" + vrna_pbacktrack_mem_free(s) - The centroid is the structure with the minimal average distance to all other structures - \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n - Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ - The distance of the centroid to the ensemble is written to the memory adressed by @a dist. + @brief Release memory occupied by a Boltzmann sampling memory data structure - @ingroup centroid_fold - @param[in] fc The fold compound data structure - @param[out] dist A pointer to the distance variable where the centroid distance will be written to - @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) + @see #vrna_pbacktrack_mem_t, vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), + vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb() + + @param s The non-redundancy memory data structure ### Prototype ```c -char * vrna_centroid(vrna_fold_compound_t *fc, double *dist); +void vrna_pbacktrack_mem_free(vrna_pbacktrack_mem_t s); ``` """ -function vrna_centroid(fc, dist) - ccall((:vrna_centroid, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Ptr{Cdouble}), fc, dist) +function vrna_pbacktrack_mem_free(s) + ccall((:vrna_pbacktrack_mem_free, libRNA), Cvoid, (vrna_pbacktrack_mem_t,), s) end """ - vrna_centroid_from_plist(length, dist, pl) + vrna_pf(fc, structure) - @brief Get the centroid structure of the ensemble + @brief Compute the partition function @f\$Q@f\$ for a given RNA sequence, or sequence alignment - This function is a threadsafe replacement for @ref centroid() with a #vrna_ep_t input + If @a structure is not a NULL pointer on input, it contains on + return a string consisting of the letters " . , | { } ( ) " denoting + bases that are essentially unpaired, weakly paired, strongly paired without + preference, weakly upstream (downstream) paired, or strongly up- + (down-)stream paired bases, respectively. + If the model's compute_bpp is set to 0 base pairing probabilities will not + be computed (saving CPU time), otherwise after calculations took place #pr will + contain the probability that bases @a i and @a j pair. - The centroid is the structure with the minimal average distance to all other structures - \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n - Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ - The distance of the centroid to the ensemble is written to the memory adressed by @a dist. + @note This function is polymorphic. It accepts #vrna_fold_compound_t of type + #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + Also, this function may return #INF / 100. in case of contradicting constraints + or numerical over-/underflow. In the latter case, a corresponding warning + will be issued to @p stdout. - @ingroup centroid_fold - @param[in] length The length of the sequence - @param[out] dist A pointer to the distance variable where the centroid distance will be written to - @param[in] pl A pair list containing base pair probability information about the ensemble - @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) + @see #vrna_fold_compound_t, vrna_fold_compound(), vrna_pf_fold(), vrna_pf_circfold(), + vrna_fold_compound_comparative(), vrna_pf_alifold(), vrna_pf_circalifold(), + vrna_db_from_probs(), vrna_exp_params(), vrna_aln_pinfo() + + @param[in,out] fc The fold compound data structure + @param[in,out] structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol ### Prototype ```c -char * vrna_centroid_from_plist(int length, double *dist, vrna_ep_t *pl); +FLT_OR_DBL vrna_pf(vrna_fold_compound_t *fc, char *structure); ``` """ -function vrna_centroid_from_plist(length, dist, pl) - ccall((:vrna_centroid_from_plist, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{vrna_ep_t}), length, dist, pl) +function vrna_pf(fc, structure) + ccall((:vrna_pf, libRNA), FLT_OR_DBL, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - vrna_centroid_from_probs(length, dist, probs) + vrna_pf_dimer(fc, structure) - @brief Get the centroid structure of the ensemble + @brief Calculate partition function and base pair probabilities of + nucleic acid/nucleic acid dimers - This function is a threadsafe replacement for @ref centroid() with a probability array input + This is the cofold partition function folding. - The centroid is the structure with the minimal average distance to all other structures - \\n @f\$ = \\sum_{(i,j) \\in S} (1-p_{ij}) + \\sum_{(i,j) \\notin S} p_{ij} @f\$ \\n - Thus, the centroid is simply the structure containing all pairs with @f\$p_ij>0.5@f\$ - The distance of the centroid to the ensemble is written to the memory adressed by @a dist. + @note This function may return #INF / 100. for the @p FA, @p FB, @p FAB, @p F0AB + members of the output data structure in case of contradicting constraints + or numerical over-/underflow. In the latter case, a corresponding warning + will be issued to @p stdout. - @ingroup centroid_fold - @param[in] length The length of the sequence - @param[out] dist A pointer to the distance variable where the centroid distance will be written to - @param[in] probs An upper triangular matrix containing base pair probabilities (access via iindx @ref vrna_idx_row_wise() ) - @return The centroid structure of the ensemble in dot-bracket notation (@p NULL on error) + @see vrna_fold_compound() for how to retrieve the necessary data structure + + @param fc the fold compound data structure + @param structure Will hold the structure or constraints + @return vrna_dimer_pf_t structure containing a set of energies needed for + concentration computations. ### Prototype ```c -char * vrna_centroid_from_probs(int length, double *dist, FLT_OR_DBL *probs); +vrna_dimer_pf_t vrna_pf_dimer(vrna_fold_compound_t *fc, char *structure); ``` """ -function vrna_centroid_from_probs(length, dist, probs) - ccall((:vrna_centroid_from_probs, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{FLT_OR_DBL}), length, dist, probs) +function vrna_pf_dimer(fc, structure) + ccall((:vrna_pf_dimer, libRNA), vrna_dimer_pf_t, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) end """ - get_centroid_struct_pl(length, dist, pl) + vrna_pf_substrands(fc, complex_size) ### Prototype ```c -; +FLT_OR_DBL * vrna_pf_substrands(vrna_fold_compound_t *fc, size_t complex_size); ``` """ -function get_centroid_struct_pl(length, dist, pl) - ccall((:get_centroid_struct_pl, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{vrna_ep_t}), length, dist, pl) +function vrna_pf_substrands(fc, complex_size) + ccall((:vrna_pf_substrands, libRNA), Ptr{FLT_OR_DBL}, (Ptr{vrna_fold_compound_t}, Csize_t), fc, complex_size) end """ - get_centroid_struct_pr(length, dist, pr) + vrna_pf_add(dG1, dG2, kT) ### Prototype ```c -; +FLT_OR_DBL vrna_pf_add(FLT_OR_DBL dG1, FLT_OR_DBL dG2, double kT); ``` """ -function get_centroid_struct_pr(length, dist, pr) - ccall((:get_centroid_struct_pr, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}, Ptr{FLT_OR_DBL}), length, dist, pr) +function vrna_pf_add(dG1, dG2, kT) + ccall((:vrna_pf_add, libRNA), FLT_OR_DBL, (FLT_OR_DBL, FLT_OR_DBL, Cdouble), dG1, dG2, kT) end -# typedef void ( * vrna_bs_result_f ) ( const char * structure , void * data ) -""" - @brief Callback for Boltzmann sampling - -@callback -@parblock -This function will be called for each secondary structure that has been successfully backtraced -from the partition function DP matrices. -@endparblock - -@see vrna_pbacktrack5_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), - vrna_pbacktrack_resume_cb() - -@param structure The secondary structure in dot-bracket notation -@param data Some arbitrary, auxiliary data address as provided to the calling function """ -const vrna_bs_result_f = Ptr{Cvoid} - -# DEPRECATED -const vrna_boltzmann_sampling_callback = Cvoid - -mutable struct vrna_pbacktrack_memory_s end + vrna_pf_fold(sequence, structure, pl) -""" - @brief Boltzmann sampling memory data structure + @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an RNA + sequence using a comparative method - This structure is required for properly resuming a previous sampling round in - specialized Boltzmann sampling, such as non-redundant backtracking. + This simplified interface to vrna_pf() computes the partition function and, if required, + base pair probabilities for an RNA sequence using default options. Memory required for + dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of + this function, the recursively filled matrices are not available any more for any post-processing. - Initialize with @p NULL and pass its address to the corresponding - functions vrna_pbacktrack5_resume(), etc. + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_pf(), + and the data structure #vrna_fold_compound_t instead. - @note Do not forget to release memory occupied by this data structure before - losing its context! Use vrna_pbacktrack_mem_free(). + @see vrna_pf_circfold(), vrna_pf(), vrna_fold_compound(), #vrna_fold_compound_t - @see vrna_pbacktrack5_resume(), vrna_pbacktrack_resume(), vrna_pbacktrack5_resume_cb(), - vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_free() + @param sequence RNA sequence + @param structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) + @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol +### Prototype +```c +float vrna_pf_fold(const char *sequence, char *structure, vrna_ep_t **pl); +``` """ -const vrna_pbacktrack_mem_t = Ptr{vrna_pbacktrack_memory_s} +function vrna_pf_fold(sequence, structure, pl) + ccall((:vrna_pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequence, structure, pl) +end """ - vrna_pbacktrack5(fc, length) - - @brief Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability - - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a secondary structure. The parameter @p length specifies the length - of the substructure starting from the 5' end. - - The structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + vrna_pf_circfold(sequence, structure, pl) - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for a circular + RNA sequences using a comparative method - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + This simplified interface to vrna_pf() computes the partition function and, if required, + base pair probabilities for a circular RNA sequence using default options. Memory required for + dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of + this function, the recursively filled matrices are not available any more for any post-processing. - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_pf(), + and the data structure #vrna_fold_compound_t instead. - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + Folding of circular RNA sequences is handled as a post-processing step of the forward + recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. - @see vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack() + @see vrna_pf_fold(), vrna_pf(), vrna_fold_compound(), #vrna_fold_compound_t - @param fc The fold compound data structure - @param length The length of the subsequence to consider (starting with 5' end) - @return A sampled secondary structure in dot-bracket notation (or NULL on error) + @param sequence A circular RNA sequence + @param structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) + @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol ### Prototype ```c -char * vrna_pbacktrack5(vrna_fold_compound_t *fc, unsigned int length); +float vrna_pf_circfold(const char *sequence, char *structure, vrna_ep_t **pl); ``` """ -function vrna_pbacktrack5(fc, length) - ccall((:vrna_pbacktrack5, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cuint), fc, length) +function vrna_pf_circfold(sequence, structure, pl) + ccall((:vrna_pf_circfold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequence, structure, pl) end """ - vrna_pbacktrack5_num(fc, num_samples, length, options) - - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. - - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability - - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] - - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. - - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. + vrna_pf_alifold(sequences, structure, pl) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an RNA + sequence alignment using a comparative method - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + This simplified interface to vrna_pf() computes the partition function and, if required, + base pair probabilities for an RNA sequence alignment using default options. Memory required for + dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of + this function, the recursively filled matrices are not available any more for any post-processing. - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_pf(), + and the data structure #vrna_fold_compound_t instead. - @see vrna_pbacktrack5(), vrna_pbacktrack5_cb(), vrna_pbacktrack_num(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + @see vrna_pf_circalifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param length The length of the subsequence to consider (starting with 5' end) - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) + @param sequences RNA sequence alignment + @param structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) + @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol ### Prototype ```c -char ** vrna_pbacktrack5_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, unsigned int options); +float vrna_pf_alifold(const char **sequences, char *structure, vrna_ep_t **pl); ``` """ -function vrna_pbacktrack5_num(fc, num_samples, length, options) - ccall((:vrna_pbacktrack5_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint), fc, num_samples, length, options) +function vrna_pf_alifold(sequences, structure, pl) + ccall((:vrna_pf_alifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequences, structure, pl) end """ - vrna_pbacktrack5_cb(fc, num_samples, length, cb, data, options) + vrna_pf_circalifold(sequences, structure, pl) - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an alignment + of circular RNA sequences using a comparative method - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. + This simplified interface to vrna_pf() computes the partition function and, if required, + base pair probabilities for an RNA sequence alignment using default options. Memory required for + dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of + this function, the recursively filled matrices are not available any more for any post-processing. - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + @note In case you want to use the filled DP matrices for any subsequent post-processing step, or + you require other conditions than specified by the default model details, use vrna_pf(), + and the data structure #vrna_fold_compound_t instead. - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + Folding of circular RNA sequences is handled as a post-processing step of the forward + recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + @see vrna_pf_alifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. + @param sequences Sequence alignment of circular RNAs + @param structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) + @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol +### Prototype +```c +float vrna_pf_circalifold(const char **sequences, char *structure, vrna_ep_t **pl); +``` +""" +function vrna_pf_circalifold(sequences, structure, pl) + ccall((:vrna_pf_circalifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequences, structure, pl) +end - In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the - structure samples through a callback mechanism. +""" + vrna_pf_co_fold(seq, structure, pl) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @brief Calculate partition function and base pair probabilities of + nucleic acid/nucleic acid dimers - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + This simplified interface to vrna_pf_dimer() computes the partition + function and, if required, base pair probabilities for an RNA-RNA + interaction using default options. Memory required for dynamic + programming (DP) matrices will be allocated and free'd on-the-fly. + Hence, after return of this function, the recursively filled matrices + are not available any more for any post-processing. - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @note In case you want to use the filled DP matrices for any subsequent + post-processing step, or you require other conditions than + specified by the default model details, use vrna_pf_dimer(), + and the data structure #vrna_fold_compound_t instead. - @see vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + @see vrna_pf_dimer() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param length The length of the subsequence to consider (starting with 5' end) - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced + @ingroup pf_cofold + @param seq Two concatenated RNA sequences with a delimiting '&' in between + @param structure A pointer to the character array where position-wise pairing propensity + will be stored. (Maybe NULL) + @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) + @return vrna_dimer_pf_t structure containing a set of energies needed for + concentration computations. ### Prototype ```c -unsigned int vrna_pbacktrack5_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, unsigned int options); +vrna_dimer_pf_t vrna_pf_co_fold(const char *seq, char *structure, vrna_ep_t **pl); ``` """ -function vrna_pbacktrack5_cb(fc, num_samples, length, cb, data, options) - ccall((:vrna_pbacktrack5_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, length, cb, data, options) +function vrna_pf_co_fold(seq, structure, pl) + ccall((:vrna_pf_co_fold, libRNA), vrna_dimer_pf_t, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), seq, structure, pl) end """ - vrna_pbacktrack5_resume(fc, num_samples, length, nr_mem, options) + vrna_pf_float_precision() - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + @brief Find out whether partition function computations are using + single precision floating points - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. + @ingroup pf_fold - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + @see #FLT_OR_DBL - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + @return 1 if single precision is used, 0 otherwise +### Prototype +```c +int vrna_pf_float_precision(void); +``` +""" +function vrna_pf_float_precision() + ccall((:vrna_pf_float_precision, libRNA), Cint, ()) +end - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. +""" + pf_fold_par(sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. - In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous - sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. - For that purpose, the user passes the address of a Boltzmann sampling data structure - (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each - successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume(). +### Prototype +```c +; +``` +""" +function pf_fold_par(sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) + ccall((:pf_fold_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_exp_param_t}, Cint, Cint, Cint), sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) +end - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; +""" + pf_fold(sequence, structure) -// sample the first 100 structures -vrna_pbacktrack5_resume(fc, - 100, - fc->length, - &nonredundant_memory, - options); -// sample another 500 structures -vrna_pbacktrack5_resume(fc, - 500, - fc->length, - &nonredundant_memory, - options); +### Prototype +```c +; +``` +""" +function pf_fold(sequence, structure) + ccall((:pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +end -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode +""" + pf_circ_fold(sequence, structure) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +### Prototype +```c +; +``` +""" +function pf_circ_fold(sequence, structure) + ccall((:pf_circ_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +end - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. +""" + pbacktrack(sequence) - @see vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param length The length of the subsequence to consider (starting with 5' end) - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -char ** vrna_pbacktrack5_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +; ``` """ -function vrna_pbacktrack5_resume(fc, num_samples, length, nr_mem, options) - ccall((:vrna_pbacktrack5_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, length, nr_mem, options) +function pbacktrack(sequence) + ccall((:pbacktrack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), sequence) end """ - vrna_pbacktrack5_resume_cb(fc, num_samples, length, cb, data, nr_mem, options) + pbacktrack5(sequence, length) - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. +### Prototype +```c +; +``` +""" +function pbacktrack5(sequence, length) + ccall((:pbacktrack5, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cint), sequence, length) +end - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +""" + pbacktrack_circ(sequence) - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. +### Prototype +```c +; +``` +""" +function pbacktrack_circ(sequence) + ccall((:pbacktrack_circ, libRNA), Ptr{Cchar}, (Ptr{Cchar},), sequence) +end + +""" + free_pf_arrays() + + +### Prototype +```c +; +``` +""" +function free_pf_arrays() + ccall((:free_pf_arrays, libRNA), Cvoid, ()) +end + +""" + update_pf_params(length) - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. - In contrast to vrna_pbacktrack5_resume() this function yields the structure samples - through a callback mechanism. +### Prototype +```c +; +``` +""" +function update_pf_params(length) + ccall((:update_pf_params, libRNA), Cvoid, (Cint,), length) +end - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; +""" + update_pf_params_par(length, parameters) -// sample the first 100 structures -vrna_pbacktrack5_resume_cb(fc, - 100, - fc->length, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); -// sample another 500 structures -vrna_pbacktrack5_resume_cb(fc, - 500, - fc->length, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); +### Prototype +```c +; +``` +""" +function update_pf_params_par(length, parameters) + ccall((:update_pf_params_par, libRNA), Cvoid, (Cint, Ptr{vrna_exp_param_t}), length, parameters) +end -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode +""" + export_bppm() - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +### Prototype +```c +; +``` +""" +function export_bppm() + ccall((:export_bppm, libRNA), Ptr{FLT_OR_DBL}, ()) +end - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. +""" + get_pf_arrays(S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) - @see vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param length The length of the subsequence to consider (starting with 5' end) - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced ### Prototype ```c -unsigned int vrna_pbacktrack5_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int length, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +; ``` """ -function vrna_pbacktrack5_resume_cb(fc, num_samples, length, cb, data, nr_mem, options) - ccall((:vrna_pbacktrack5_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, length, cb, data, nr_mem, options) +function get_pf_arrays(S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) + ccall((:get_pf_arrays, libRNA), Cint, (Ptr{Ptr{Cshort}}, Ptr{Ptr{Cshort}}, Ptr{Ptr{Cchar}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}), S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) end """ - vrna_pbacktrack(fc) - - @brief Sample a secondary structure from the Boltzmann ensemble according its probability + get_subseq_F(i, j) - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a secondary structure. - The structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +### Prototype +```c +; +``` +""" +function get_subseq_F(i, j) + ccall((:get_subseq_F, libRNA), Cdouble, (Cint, Cint), i, j) +end - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] +""" + mean_bp_distance(length) - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices +### Prototype +```c +; +``` +""" +function mean_bp_distance(length) + ccall((:mean_bp_distance, libRNA), Cdouble, (Cint,), length) +end - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +""" + mean_bp_distance_pr(length, pr) - @see vrna_pbacktrack5(), vrna_pbacktrack_num, vrna_pbacktrack_cb() - @param fc The fold compound data structure - @return A sampled secondary structure in dot-bracket notation (or NULL on error) ### Prototype ```c -char * vrna_pbacktrack(vrna_fold_compound_t *fc); +; ``` """ -function vrna_pbacktrack(fc) - ccall((:vrna_pbacktrack, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t},), fc) +function mean_bp_distance_pr(length, pr) + ccall((:mean_bp_distance_pr, libRNA), Cdouble, (Cint, Ptr{FLT_OR_DBL}), length, pr) end """ - vrna_pbacktrack_num(fc, num_samples, options) + stackProb(cutoff) - @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. +### Prototype +```c +; +``` +""" +function stackProb(cutoff) + ccall((:stackProb, libRNA), Ptr{vrna_ep_t}, (Cdouble,), cutoff) +end - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +""" + init_pf_fold(length) - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. +### Prototype +```c +; +``` +""" +function init_pf_fold(length) + ccall((:init_pf_fold, libRNA), Cvoid, (Cint,), length) +end - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. +""" + centroid(length, dist) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +### Prototype +```c +; +``` +""" +function centroid(length, dist) + ccall((:centroid, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}), length, dist) +end - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. +""" + get_centroid_struct_gquad_pr(length, dist) - @see vrna_pbacktrack(), vrna_pbacktrack_cb(), vrna_pbacktrack5_num(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) ### Prototype ```c -char ** vrna_pbacktrack_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int options); +; ``` """ -function vrna_pbacktrack_num(fc, num_samples, options) - ccall((:vrna_pbacktrack_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, num_samples, options) +function get_centroid_struct_gquad_pr(length, dist) + ccall((:get_centroid_struct_gquad_pr, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}), length, dist) end """ - vrna_pbacktrack_cb(fc, num_samples, cb, data, options) - - @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability + mean_bp_dist(length) - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +### Prototype +```c +; +``` +""" +function mean_bp_dist(length) + ccall((:mean_bp_dist, libRNA), Cdouble, (Cint,), length) +end - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] +""" + expLoopEnergy(u1, u2, type, type2, si1, sj1, sp1, sq1) - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. +### Prototype +```c +; +``` +""" +function expLoopEnergy(u1, u2, type, type2, si1, sj1, sp1, sq1) + ccall((:expLoopEnergy, libRNA), Cdouble, (Cint, Cint, Cint, Cint, Cshort, Cshort, Cshort, Cshort), u1, u2, type, type2, si1, sj1, sp1, sq1) +end - In contrast to vrna_pbacktrack() and vrna_pbacktrack_num() this function yields the - structure samples through a callback mechanism. +""" + expHairpinEnergy(u, type, si1, sj1, string) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +### Prototype +```c +; +``` +""" +function expHairpinEnergy(u, type, si1, sj1, string) + ccall((:expHairpinEnergy, libRNA), Cdouble, (Cint, Cint, Cshort, Cshort, Ptr{Cchar}), u, type, si1, sj1, string) +end - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. +""" + assign_plist_gquad_from_pr(pl, length, cut_off) - @see vrna_pbacktrack(), vrna_pbacktrack_num(), vrna_pbacktrack5_cb(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced ### Prototype ```c -unsigned int vrna_pbacktrack_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, unsigned int options); +; ``` """ -function vrna_pbacktrack_cb(fc, num_samples, cb, data, options) - ccall((:vrna_pbacktrack_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, cb, data, options) +function assign_plist_gquad_from_pr(pl, length, cut_off) + ccall((:assign_plist_gquad_from_pr, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Cint, Cdouble), pl, length, cut_off) end +# typedef void ( * vrna_probs_window_f ) ( FLT_OR_DBL * pr , int pr_size , int i , int max , unsigned int type , void * data ) """ - vrna_pbacktrack_resume(fc, num_samples, nr_mem, options) +@brief Sliding window probability computation callback - @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability +@callback +@parblock +This function will be called for each probability data set in the sliding +window probability computation implementation of vrna_probs_window(). +The argument @a type specifies the type of probability that is passed to +this function. +@endparblock - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. +#### Types: #### + * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP + * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP + * #VRNA_PROBS_WINDOW_PF - @copybrief #VRNA_PROBS_WINDOW_PF - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +The above types usually come exclusively. However, for unpaired +probabilities, the #VRNA_PROBS_WINDOW_UP flag is OR-ed together +with one of the loop type contexts - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + * #VRNA_EXT_LOOP - @copybrief #VRNA_EXT_LOOP + * #VRNA_HP_LOOP - @copybrief #VRNA_HP_LOOP + * #VRNA_INT_LOOP - @copybrief #VRNA_INT_LOOP + * #VRNA_MB_LOOP - @copybrief #VRNA_MB_LOOP + * #VRNA_ANY_LOOP - @copybrief #VRNA_ANY_LOOP - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. +to indicate the particular type of data available through the @p pr +pointer. - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. +@see vrna_probs_window(), vrna_pfl_fold_up_cb() - In contrast to vrna_pbacktrack_cb() this function allows for resuming a previous - sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. - For that purpose, the user passes the address of a Boltzmann sampling data structure - (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each - successive call to vrna_pbacktrack_resume_cb() or vrna_pbacktrack_resume(). +@param pr An array of probabilities +@param pr_size The length of the probability array +@param i The i-position (5') of the probabilities +@param max The (theoretical) maximum length of the probability array +@param type The type of data that is provided +@param data Auxiliary data +""" +const vrna_probs_window_f = Ptr{Cvoid} - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; +# DEPRECATED +const vrna_probs_window_callback = Cvoid -// sample the first 100 structures -vrna_pbacktrack_resume(fc, - 100, - &nonredundant_memory, - options); +""" + vrna_probs_window(fc, ulength, options, cb, data) -// sample another 500 structures -vrna_pbacktrack_resume(fc, - 500, - &nonredundant_memory, - options); + @brief Compute various equilibrium probabilities under a sliding window approach -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode + This function applies a sliding window scan for the sequence provided with the + argument @p fc and reports back equilibrium probabilities through the callback + function @p cb. The data reported to the callback depends on the @p options flag. - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @note The parameter @p ulength only affects computation and resulting data if unpaired + probability computations are requested through the @p options flag. - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + #### Options: #### + * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP + * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP + * #VRNA_PROBS_WINDOW_UP_SPLIT - @copybrief #VRNA_PROBS_WINDOW_UP_SPLIT - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + Options may be OR-ed together - @see vrna_pbacktrack_resume_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free + @see vrna_pfl_fold_cb(), vrna_pfl_fold_up_cb() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) + @param fc The fold compound with sequence data, model settings and precomputed energy parameters + @param ulength The maximal length of an unpaired segment (only for unpaired probability computations) + @param cb The callback function which collects the pair probability data for further processing + @param data Some arbitrary data structure that is passed to the callback @p cb + @param options Option flags to control the behavior of this function + @return 0 on failure, non-zero on success ### Prototype ```c -char ** vrna_pbacktrack_resume(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +int vrna_probs_window(vrna_fold_compound_t *fc, int ulength, unsigned int options, vrna_probs_window_f cb, void *data); ``` """ -function vrna_pbacktrack_resume(fc, num_samples, nr_mem, options) - ccall((:vrna_pbacktrack_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, nr_mem, options) +function vrna_probs_window(fc, ulength, options, cb, data) + ccall((:vrna_probs_window, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cuint, vrna_probs_window_f, Ptr{Cvoid}), fc, ulength, options, cb, data) end """ - vrna_pbacktrack_resume_cb(fc, num_samples, cb, data, nr_mem, options) + vrna_pfl_fold(sequence, window_size, max_bp_span, cutoff) - @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability + @brief Compute base pair probabilities using a sliding-window approach - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. + This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, + a window size, a maximum base pair span, and a cutoff value computes the pair probabilities + for any base pair in any window. The pair probabilities are returned as a list and the user + has to take care to free() the memory occupied by the list. - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + @note This function uses default model settings! For custom model settings, we refer to + the function vrna_probs_window().
+ In case of any computation errors, this function returns @p NULL - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + @see vrna_probs_window(), vrna_pfl_fold_cb(), vrna_pfl_fold_up() - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + @param sequence The nucleic acid input sequence + @param window_size The size of the sliding window + @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs + @param cutoff A cutoff value that omits all pairs with lower probability + @return A list of base pair probabilities, terminated by an entry with #vrna_ep_t.i and #vrna_ep_t.j set to 0 +### Prototype +```c +vrna_ep_t * vrna_pfl_fold(const char *sequence, int window_size, int max_bp_span, float cutoff); +``` +""" +function vrna_pfl_fold(sequence, window_size, max_bp_span, cutoff) + ccall((:vrna_pfl_fold, libRNA), Ptr{vrna_ep_t}, (Ptr{Cchar}, Cint, Cint, Cfloat), sequence, window_size, max_bp_span, cutoff) +end - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. +""" + vrna_pfl_fold_cb(sequence, window_size, max_bp_span, cb, data) - In contrast to vrna_pbacktrack5_resume() this function yields the structure samples - through a callback mechanism. + @brief Compute base pair probabilities using a sliding-window approach (callback version) - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; + This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, + a window size, a maximum base pair span, and a cutoff value computes the pair probabilities + for any base pair in any window. It is similar to vrna_pfl_fold() but uses a callback mechanism + to return the pair probabilities. -// sample the first 100 structures -vrna_pbacktrack5_resume_cb(fc, - 100, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); + Read the details for vrna_probs_window() for details on the callback implementation! -// sample another 500 structures -vrna_pbacktrack5_resume_cb(fc, - 500, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); + @note This function uses default model settings! For custom model settings, we refer to + the function vrna_probs_window(). -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode + @see vrna_probs_window(), vrna_pfl_fold(), vrna_pfl_fold_up_cb() - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @param sequence The nucleic acid input sequence + @param window_size The size of the sliding window + @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs + @param cb The callback function which collects the pair probability data for further processing + @param data Some arbitrary data structure that is passed to the callback @p cb + @return 0 on failure, non-zero on success +### Prototype +```c +int vrna_pfl_fold_cb(const char *sequence, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data); +``` +""" +function vrna_pfl_fold_cb(sequence, window_size, max_bp_span, cb, data) + ccall((:vrna_pfl_fold_cb, libRNA), Cint, (Ptr{Cchar}, Cint, Cint, vrna_probs_window_f, Ptr{Cvoid}), sequence, window_size, max_bp_span, cb, data) +end - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +""" + vrna_pfl_fold_up(sequence, ulength, window_size, max_bp_span) - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @brief Compute probability of contiguous unpaired segments - @see vrna_pbacktrack_resume(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free + This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, + a maximum length of unpaired segments (@p ulength), a window size, and a maximum base + pair span computes the equilibrium probability of any segment not exceeding @p ulength. + The probabilities to be unpaired are returned as a 1-based, 2-dimensional matrix with + dimensions @f\$ N \\times M @f\$, where @f\$N@f\$ is the length of the sequence and @f\$M@f\$ + is the maximum segment length. As an example, the probability of a segment of size 5 + starting at position 100 is stored in the matrix entry @f\$X[100][5]@f\$. + + It is the users responsibility to free the memory occupied by this matrix. - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced + @note This function uses default model settings! For custom model settings, we refer to + the function vrna_probs_window(). + + @param sequence The nucleic acid input sequence + @param ulength The maximal length of an unpaired segment + @param window_size The size of the sliding window + @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs + @return The probabilities to be unpaired for any segment not exceeding @p ulength ### Prototype ```c -unsigned int vrna_pbacktrack_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +double ** vrna_pfl_fold_up(const char *sequence, int ulength, int window_size, int max_bp_span); ``` """ -function vrna_pbacktrack_resume_cb(fc, num_samples, cb, data, nr_mem, options) - ccall((:vrna_pbacktrack_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, cb, data, nr_mem, options) +function vrna_pfl_fold_up(sequence, ulength, window_size, max_bp_span) + ccall((:vrna_pfl_fold_up, libRNA), Ptr{Ptr{Cdouble}}, (Ptr{Cchar}, Cint, Cint, Cint), sequence, ulength, window_size, max_bp_span) end """ - vrna_pbacktrack_sub(fc, start, _end) - - @brief Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability - - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a secondary structure. The parameters @p start and @p end specify the interval - @f\$ [start:end] @f\$ of the subsequence with @f\$ 1 \\leq start < end \\leq n@f\$ for sequence length @f\$ n @f\$, - the structure @f\$ s_{start,end} @f\$ should be drawn from. - - The resulting substructure @f\$ s_{start,end} @f\$ with free energy @f\$ E(s_{start, end}) @f\$ is picked from - the Boltzmann distributed sub ensemble of all structures within the interval @f\$ [start:end] @f\$ according - to its probability + vrna_pfl_fold_up_cb(sequence, ulength, window_size, max_bp_span, cb, data) - @f[ - p(s_{start,end}) = \\frac{exp(-E(s_{start,end}) / kT)}{Z_{start,end}} - @f] + @brief Compute probability of contiguous unpaired segments - with partition function @f\$ Z_{start,end} = \\sum_{s_{start,end}} exp(-E(s_{start,end}) / kT) @f\$, - Boltzmann constant @f\$ k @f\$ and thermodynamic temperature @f\$ T @f\$. + This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, + a maximum length of unpaired segments (@p ulength), a window size, and a maximum base + pair span computes the equilibrium probability of any segment not exceeding @p ulength. + It is similar to vrna_pfl_fold_up() but uses a callback mechanism to return the unpaired + probabilities. - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + Read the details for vrna_probs_window() for details on the callback implementation! - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - @see vrna_pbacktrack_sub_num(), vrna_pbacktrack_sub_cb(), vrna_pbacktrack() + @note This function uses default model settings! For custom model settings, we refer to + the function vrna_probs_window(). - @param fc The fold compound data structure - @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) - @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) - @return A sampled secondary structure in dot-bracket notation (or NULL on error) + @param sequence The nucleic acid input sequence + @param ulength The maximal length of an unpaired segment + @param window_size The size of the sliding window + @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs + @param cb The callback function which collects the pair probability data for further processing + @param data Some arbitrary data structure that is passed to the callback @p cb + @return 0 on failure, non-zero on success ### Prototype ```c -char * vrna_pbacktrack_sub(vrna_fold_compound_t *fc, unsigned int start, unsigned int end); +int vrna_pfl_fold_up_cb(const char *sequence, int ulength, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data); ``` """ -function vrna_pbacktrack_sub(fc, start, _end) - ccall((:vrna_pbacktrack_sub, libRNA), Ptr{Cchar}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, start, _end) +function vrna_pfl_fold_up_cb(sequence, ulength, window_size, max_bp_span, cb, data) + ccall((:vrna_pfl_fold_up_cb, libRNA), Cint, (Ptr{Cchar}, Cint, Cint, Cint, vrna_probs_window_f, Ptr{Cvoid}), sequence, ulength, window_size, max_bp_span, cb, data) end -""" - vrna_pbacktrack_sub_num(fc, num_samples, start, _end, options) +struct vrna_plot_layout_s + length::Cuint + x::Ptr{Cfloat} + y::Ptr{Cfloat} + arcs::Ptr{Cdouble} + bbox::NTuple{4, Cint} +end - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability +""" + @brief RNA secondary structure figure layout - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. + @see vrna_plot_layout(), vrna_plot_layout_free(), vrna_plot_layout_simple(), + vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), + vrna_plot_layout_puzzler() +""" +const vrna_plot_layout_t = vrna_plot_layout_s - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability +""" + vrna_plot_coords_turtle(structure, x, y, arc_coords) - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + @brief Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_TURTLE. - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. + Here is a simple example how to use this function, assuming variable @p structure contains + a valid dot-bracket string: + @code{.c} + float *x, *y; + double *arcs; - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + if (vrna_plot_coords_turtle(structure, &x, &y, &arcs)) { + printf("all fine"); + } else { + printf("some failure occured!"); + } - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + free(x); + free(y); + free(arcs); + @endcode - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @note On success, this function allocates memory for X, Y and arc coordinates and assigns + the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! - @see vrna_pbacktrack_sub(), vrna_pbacktrack_sub_cb(), vrna_pbacktrack_num(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + @see vrna_plot_coords(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_circular(), + vrna_plot_coords_simple(), vrna_plot_coords_naview(), vrna_plot_coords_puzzler() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) - @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) + @param structure The secondary structure in dot-bracket notation + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -char ** vrna_pbacktrack_sub_num(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, unsigned int options); +int vrna_plot_coords_turtle(const char *structure, float **x, float **y, double **arc_coords); ``` """ -function vrna_pbacktrack_sub_num(fc, num_samples, start, _end, options) - ccall((:vrna_pbacktrack_sub_num, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Cuint), fc, num_samples, start, _end, options) +function vrna_plot_coords_turtle(structure, x, y, arc_coords) + ccall((:vrna_plot_coords_turtle, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}), structure, x, y, arc_coords) end """ - vrna_pbacktrack_sub_cb(fc, num_samples, start, _end, cb, data, options) + vrna_plot_coords_turtle_pt(pair_table, x, y, arc_coords) - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + @brief Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. + Same as vrna_plot_coords_turtle() but takes a pair table with the structure + information as input. - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + @note On success, this function allocates memory for X, Y and arc coordinates and assigns + the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] + @see vrna_plot_coords_pt(), vrna_plot_coords_turtle(), vrna_plot_coords_circular_pt(), + vrna_plot_coords_simple_pt(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_naview_pt() - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + @param pt The pair table that holds the secondary structure + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise +### Prototype +```c +int vrna_plot_coords_turtle_pt(short const *const pair_table, float **x, float **y, double **arc_coords); +``` +""" +function vrna_plot_coords_turtle_pt(pair_table, x, y, arc_coords) + ccall((:vrna_plot_coords_turtle_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}), pair_table, x, y, arc_coords) +end - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. +""" + vrna_plot_options_puzzler_t - In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the - structure samples through a callback mechanism. + @brief Options data structure for RNApuzzler algorithm implementation +""" +struct vrna_plot_options_puzzler_t + drawArcs::Cshort + paired::Cdouble + unpaired::Cdouble + checkAncestorIntersections::Cshort + checkSiblingIntersections::Cshort + checkExteriorIntersections::Cshort + allowFlipping::Cshort + optimize::Cshort + maximumNumberOfConfigChangesAllowed::Cint + config::Ptr{Cchar} + filename::Ptr{Cchar} + numberOfChangesAppliedToConfig::Cint + psNumber::Cint +end - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices +""" + vrna_plot_coords_puzzler(structure, x, y, arc_coords, options) - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + @brief Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_PUZZLER. - @see vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), - #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT + Here is a simple example how to use this function, assuming variable @p structure contains + a valid dot-bracket string and using the default options (@p options = NULL): + @code{.c} + float *x, *y; + double *arcs; + + if (vrna_plot_coords_puzzler(structure, &x, &y, &arcs, NULL)) { + printf("all fine"); + } else { + printf("some failure occured!"); + } + + free(x); + free(y); + free(arcs); + @endcode + + @note On success, this function allocates memory for X, Y and arc coordinates and assigns + the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! + + @see vrna_plot_coords(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_circular(), + vrna_plot_coords_simple(), vrna_plot_coords_turtle(), vrna_plot_coords_naview(), + vrna_plot_options_puzzler() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) - @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced + @param structure The secondary structure in dot-bracket notation + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) + @param options The options for the RNApuzzler algorithm (or NULL) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -unsigned int vrna_pbacktrack_sub_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, unsigned int options); +int vrna_plot_coords_puzzler(const char *structure, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *options); ``` """ -function vrna_pbacktrack_sub_cb(fc, num_samples, start, _end, cb, data, options) - ccall((:vrna_pbacktrack_sub_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Cuint), fc, num_samples, start, _end, cb, data, options) +function vrna_plot_coords_puzzler(structure, x, y, arc_coords, options) + ccall((:vrna_plot_coords_puzzler, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}, Ptr{vrna_plot_options_puzzler_t}), structure, x, y, arc_coords, options) end """ - vrna_pbacktrack_sub_resume(fc, num_samples, start, _end, nr_mem, options) - - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability - - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. - - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability - - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] - - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. - - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. - - In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous - sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. - For that purpose, the user passes the address of a Boltzmann sampling data structure - (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each - successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume(). + vrna_plot_coords_puzzler_pt(pair_table, x, y, arc_coords, puzzler) - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; + @brief Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst -// sample the first 100 structures -vrna_pbacktrack5_resume(fc, - 100, - fc->length, - &nonredundant_memory, - options); + Same as vrna_plot_coords_puzzler() but takes a pair table with the structure + information as input. -// sample another 500 structures -vrna_pbacktrack5_resume(fc, - 500, - fc->length, - &nonredundant_memory, - options); + @note On success, this function allocates memory for X, Y and arc coordinates and assigns + the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode + @see vrna_plot_coords_pt(), vrna_plot_coords_puzzler(), vrna_plot_coords_circular_pt(), + vrna_plot_coords_simple_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_naview_pt() - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @param pt The pair table that holds the secondary structure + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) + @param options The options for the RNApuzzler algorithm (or NULL) + @return The length of the structure on success, 0 otherwise +### Prototype +```c +int vrna_plot_coords_puzzler_pt(short const *const pair_table, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *puzzler); +``` +""" +function vrna_plot_coords_puzzler_pt(pair_table, x, y, arc_coords, puzzler) + ccall((:vrna_plot_coords_puzzler_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}, Ptr{vrna_plot_options_puzzler_t}), pair_table, x, y, arc_coords, puzzler) +end - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. +""" + vrna_plot_options_puzzler() - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @brief Create an RNApuzzler options data structure - @see vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free + @see vrna_plot_options_puzzler_free(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), + vrna_plot_layout_puzzler() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) - @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) + @return An RNApuzzler options data structure with default settings ### Prototype ```c -char ** vrna_pbacktrack_sub_resume(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +vrna_plot_options_puzzler_t * vrna_plot_options_puzzler(void); ``` """ -function vrna_pbacktrack_sub_resume(fc, num_samples, start, _end, nr_mem, options) - ccall((:vrna_pbacktrack_sub_resume, libRNA), Ptr{Ptr{Cchar}}, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, start, _end, nr_mem, options) +function vrna_plot_options_puzzler() + ccall((:vrna_plot_options_puzzler, libRNA), Ptr{vrna_plot_options_puzzler_t}, ()) end """ - vrna_pbacktrack_sub_resume_cb(fc, num_samples, start, _end, cb, data, nr_mem, options) + vrna_plot_options_puzzler_free(options) - @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability + @brief Free memory occupied by an RNApuzzler options data structure - Perform a probabilistic (stochastic) backtracing in the partition function DP arrays - to obtain a set of @p num_samples secondary structures. The parameter @p length specifies - the length of the substructure starting from the 5' end. + @see vrna_plot_options_puzzler(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), + vrna_plot_layout_puzzler() - Any structure @f\$ s @f\$ with free energy @f\$ E(s) @f\$ is picked from the Boltzmann distributed - ensemble according to its probability + @param options A pointer to the options data structure to free +### Prototype +```c +void vrna_plot_options_puzzler_free(vrna_plot_options_puzzler_t *options); +``` +""" +function vrna_plot_options_puzzler_free(options) + ccall((:vrna_plot_options_puzzler_free, libRNA), Cvoid, (Ptr{vrna_plot_options_puzzler_t},), options) +end - @f[ - p(s) = \\frac{exp(-E(s) / kT)}{Z} - @f] +""" + vrna_plot_layout(structure, plot_type) - with partition function @f\$ Z = \\sum_s exp(-E(s) / kT) @f\$, Boltzmann constant @f\$ k @f\$ and - thermodynamic temperature @f\$ T @f\$. + @brief Create a layout (coordinates, etc.) for a secondary structure plot - Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing - mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of - @rstinline :cite:t:`michalik:2017` @endrst. + This function can be used to create a secondary structure nucleotide layout + that is then further processed by an actual plotting function. The layout + algorithm can be specified using the @p plot_type parameter, and the following + algorithms are currently supported: + - #VRNA_PLOT_TYPE_SIMPLE + - #VRNA_PLOT_TYPE_NAVIEW + - #VRNA_PLOT_TYPE_CIRCULAR + - #VRNA_PLOT_TYPE_TURTLE + - #VRNA_PLOT_TYPE_PUZZLER - In contrast to vrna_pbacktrack5_resume() this function yields the structure samples - through a callback mechanism. + Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW - A successive sample call to this function may look like: -@code{.c} -vrna_pbacktrack_mem_t nonredundant_memory = NULL; + @note If only X-Y coordinates of the corresponding structure layout are required, consider + using vrna_plot_coords() instead! -// sample the first 100 structures -vrna_pbacktrack5_resume_cb(fc, - 100, - fc->length, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); + @see vrna_plot_layout_free(), vrna_plot_layout_simple(), vrna_plot_layout_naview(), + vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), + vrna_plot_coords(), vrna_file_PS_rnaplot_layout() -// sample another 500 structures -vrna_pbacktrack5_resume_cb(fc, - 500, - fc->length, - &callback_function, - (void *)&callback_data, - &nonredundant_memory, - options); + @param structure The secondary structure in dot-bracket notation + @param plot_type The layout algorithm to be used + @return The layout data structure for the provided secondary structure +### Prototype +```c +vrna_plot_layout_t * vrna_plot_layout(const char *structure, unsigned int plot_type); +``` +""" +function vrna_plot_layout(structure, plot_type) + ccall((:vrna_plot_layout, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar}, Cuint), structure, plot_type) +end -// release memory occupied by the non-redundant memory data structure -vrna_pbacktrack_mem_free(nonredundant_memory); -@endcode +""" + vrna_plot_layout_simple(structure) - @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() - or similar. This can be done easily by passing vrna_fold_compound() a model details parameter - with vrna_md_t.uniq_ML = 1.
- vrna_pf() has to be called first to fill the partition function matrices + @brief Create a layout (coordinates, etc.) for a simple secondary structure plot - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. + This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. - @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may - not yield the full number of requested samples. This may happen if - a) the number of requested structures is larger than the total number - of structuresin the ensemble, - b) numeric instabilities prevent the backtracking function to enumerate - structures with high free energies, or - c) any other error occurs. + @note If only X-Y coordinates of the corresponding structure layout are required, consider + using vrna_plot_coords_simple() instead! - @see vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), - #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, - vrna_pbacktrack_mem_free + @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), + vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), + vrna_plot_coords_simple(), vrna_file_PS_rnaplot_layout() - @param fc The fold compound data structure - @param num_samples The size of the sample set, i.e. number of structures - @param start The start of the subsequence to consider, i.e. 5'-end position(1-based) - @param end The end of the subsequence to consider, i.e. 3'-end position (1-based) - @param cb The callback that receives the sampled structure - @param data A data structure passed through to the callback @p cb - @param nr_mem The address of the Boltzmann sampling memory data structure - @param options A bitwise OR-flag indicating the backtracing mode. - @return The number of structures actually backtraced + @param structure The secondary structure in dot-bracket notation + @return The layout data structure for the provided secondary structure ### Prototype ```c -unsigned int vrna_pbacktrack_sub_resume_cb(vrna_fold_compound_t *fc, unsigned int num_samples, unsigned int start, unsigned int end, vrna_bs_result_f cb, void *data, vrna_pbacktrack_mem_t *nr_mem, unsigned int options); +vrna_plot_layout_t * vrna_plot_layout_simple(const char *structure); ``` """ -function vrna_pbacktrack_sub_resume_cb(fc, num_samples, start, _end, cb, data, nr_mem, options) - ccall((:vrna_pbacktrack_sub_resume_cb, libRNA), Cuint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, vrna_bs_result_f, Ptr{Cvoid}, Ptr{vrna_pbacktrack_mem_t}, Cuint), fc, num_samples, start, _end, cb, data, nr_mem, options) +function vrna_plot_layout_simple(structure) + ccall((:vrna_plot_layout_simple, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) end """ - vrna_pbacktrack_mem_free(s) + vrna_plot_layout_circular(structure) - @brief Release memory occupied by a Boltzmann sampling memory data structure + @brief Create a layout (coordinates, etc.) for a circular secondary structure plot + + This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. + + @note If only X-Y coordinates of the corresponding structure layout are required, consider + using vrna_plot_coords_circular() instead! - @see #vrna_pbacktrack_mem_t, vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), - vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb() + @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), + vrna_plot_layout_simple(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), + vrna_plot_coords_circular(), vrna_file_PS_rnaplot_layout() - @param s The non-redundancy memory data structure + @param structure The secondary structure in dot-bracket notation + @return The layout data structure for the provided secondary structure ### Prototype ```c -void vrna_pbacktrack_mem_free(vrna_pbacktrack_mem_t s); +vrna_plot_layout_t * vrna_plot_layout_circular(const char *structure); ``` """ -function vrna_pbacktrack_mem_free(s) - ccall((:vrna_pbacktrack_mem_free, libRNA), Cvoid, (vrna_pbacktrack_mem_t,), s) +function vrna_plot_layout_circular(structure) + ccall((:vrna_plot_layout_circular, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) end """ - vrna_pf(fc, structure) + vrna_plot_layout_turtle(structure) - @brief Compute the partition function @f\$Q@f\$ for a given RNA sequence, or sequence alignment + @brief Create a layout (coordinates, etc.) for a secondary structure plot using the Turtle Algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - If @a structure is not a NULL pointer on input, it contains on - return a string consisting of the letters " . , | { } ( ) " denoting - bases that are essentially unpaired, weakly paired, strongly paired without - preference, weakly upstream (downstream) paired, or strongly up- - (down-)stream paired bases, respectively. - If the model's compute_bpp is set to 0 base pairing probabilities will not - be computed (saving CPU time), otherwise after calculations took place #pr will - contain the probability that bases @a i and @a j pair. + This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_TURTLE. - @note This function is polymorphic. It accepts #vrna_fold_compound_t of type - #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. - Also, this function may return #INF / 100. in case of contradicting constraints - or numerical over-/underflow. In the latter case, a corresponding warning - will be issued to @p stdout. + @note If only X-Y coordinates of the corresponding structure layout are required, consider + using vrna_plot_coords_turtle() instead! - @see #vrna_fold_compound_t, vrna_fold_compound(), vrna_pf_fold(), vrna_pf_circfold(), - vrna_fold_compound_comparative(), vrna_pf_alifold(), vrna_pf_circalifold(), - vrna_db_from_probs(), vrna_exp_params(), vrna_aln_pinfo() + @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), + vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_puzzler(), + vrna_plot_coords_turtle(), vrna_file_PS_rnaplot_layout() - @param[in,out] fc The fold compound data structure - @param[in,out] structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol + @param structure The secondary structure in dot-bracket notation + @return The layout data structure for the provided secondary structure ### Prototype ```c -FLT_OR_DBL vrna_pf(vrna_fold_compound_t *fc, char *structure); +vrna_plot_layout_t * vrna_plot_layout_turtle(const char *structure); ``` """ -function vrna_pf(fc, structure) - ccall((:vrna_pf, libRNA), FLT_OR_DBL, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_plot_layout_turtle(structure) + ccall((:vrna_plot_layout_turtle, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) end """ - vrna_pf_dimer(fc, structure) + vrna_plot_layout_puzzler(structure, options) - @brief Calculate partition function and base pair probabilities of - nucleic acid/nucleic acid dimers + @brief Create a layout (coordinates, etc.) for a secondary structure plot using the RNApuzzler Algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - This is the cofold partition function folding. + This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_PUZZLER. - @note This function may return #INF / 100. for the @p FA, @p FB, @p FAB, @p F0AB - members of the output data structure in case of contradicting constraints - or numerical over-/underflow. In the latter case, a corresponding warning - will be issued to @p stdout. + @note If only X-Y coordinates of the corresponding structure layout are required, consider + using vrna_plot_coords_puzzler() instead! - @see vrna_fold_compound() for how to retrieve the necessary data structure + @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), + vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), + vrna_plot_coords_puzzler(), vrna_file_PS_rnaplot_layout() - @param fc the fold compound data structure - @param structure Will hold the structure or constraints - @return vrna_dimer_pf_t structure containing a set of energies needed for - concentration computations. + @param structure The secondary structure in dot-bracket notation + @return The layout data structure for the provided secondary structure ### Prototype ```c -vrna_dimer_pf_t vrna_pf_dimer(vrna_fold_compound_t *fc, char *structure); +vrna_plot_layout_t * vrna_plot_layout_puzzler(const char *structure, vrna_plot_options_puzzler_t *options); ``` """ -function vrna_pf_dimer(fc, structure) - ccall((:vrna_pf_dimer, libRNA), vrna_dimer_pf_t, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +function vrna_plot_layout_puzzler(structure, options) + ccall((:vrna_plot_layout_puzzler, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar}, Ptr{vrna_plot_options_puzzler_t}), structure, options) end """ - vrna_pf_substrands(fc, complex_size) + vrna_plot_layout_free(layout) + + @brief Free memory occupied by a figure layout data structure + @see #vrna_plot_layout_t, vrna_plot_layout(), vrna_plot_layout_simple(), + vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), + vrna_plot_layout_puzzler(), vrna_file_PS_rnaplot_layout() + @param layout The layout data structure to free ### Prototype ```c -FLT_OR_DBL * vrna_pf_substrands(vrna_fold_compound_t *fc, size_t complex_size); +void vrna_plot_layout_free(vrna_plot_layout_t *layout); ``` """ -function vrna_pf_substrands(fc, complex_size) - ccall((:vrna_pf_substrands, libRNA), Ptr{FLT_OR_DBL}, (Ptr{vrna_fold_compound_t}, Csize_t), fc, complex_size) +function vrna_plot_layout_free(layout) + ccall((:vrna_plot_layout_free, libRNA), Cvoid, (Ptr{vrna_plot_layout_t},), layout) end """ - vrna_pf_add(dG1, dG2, kT) + vrna_plot_coords(structure, x, y, plot_type) + + @brief Compute nucleotide coordinates for secondary structure plot + + This function takes a secondary structure and computes X-Y coordinates + for each nucleotide that then can be used to create a structure plot. + The parameter @p plot_type is used to select the underlying layout algorithm. + Currently, the following selections are provided: + - #VRNA_PLOT_TYPE_SIMPLE + - #VRNA_PLOT_TYPE_NAVIEW + - #VRNA_PLOT_TYPE_CIRCULAR + - #VRNA_PLOT_TYPE_TURTLE + - #VRNA_PLOT_TYPE_PUZZLER + + Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW + + Here is a simple example how to use this function, assuming variable @p structure contains + a valid dot-bracket string: + @code{.c} + float *x, *y; + + if (vrna_plot_coords(structure, &x, &y)) { + printf("all fine"); + } else { + printf("some failure occured!"); + } + + free(x); + free(y); + @endcode + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! + + @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_naview() + vrna_plot_coords_circular(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() + @param structure The secondary structure in dot-bracket notation + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param plot_type The layout algorithm to be used + @return The length of the structure on success, 0 otherwise ### Prototype ```c -FLT_OR_DBL vrna_pf_add(FLT_OR_DBL dG1, FLT_OR_DBL dG2, double kT); +int vrna_plot_coords(const char *structure, float **x, float **y, int plot_type); ``` """ -function vrna_pf_add(dG1, dG2, kT) - ccall((:vrna_pf_add, libRNA), FLT_OR_DBL, (FLT_OR_DBL, FLT_OR_DBL, Cdouble), dG1, dG2, kT) +function vrna_plot_coords(structure, x, y, plot_type) + ccall((:vrna_plot_coords, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Cint), structure, x, y, plot_type) end """ - vrna_pf_fold(sequence, structure, pl) + vrna_plot_coords_pt(pt, x, y, plot_type) - @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an RNA - sequence using a comparative method + @brief Compute nucleotide coordinates for secondary structure plot - This simplified interface to vrna_pf() computes the partition function and, if required, - base pair probabilities for an RNA sequence using default options. Memory required for - dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of - this function, the recursively filled matrices are not available any more for any post-processing. + Same as vrna_plot_coords() but takes a pair table with the structure + information as input. - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_pf(), - and the data structure #vrna_fold_compound_t instead. + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! - @see vrna_pf_circfold(), vrna_pf(), vrna_fold_compound(), #vrna_fold_compound_t + @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_naview_pt() + vrna_plot_coords_circular_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() - @param sequence RNA sequence - @param structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) - @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol + @param pt The pair table that holds the secondary structure + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @param plot_type The layout algorithm to be used + @return The length of the structure on success, 0 otherwise ### Prototype ```c -float vrna_pf_fold(const char *sequence, char *structure, vrna_ep_t **pl); +int vrna_plot_coords_pt(const short *pt, float **x, float **y, int plot_type); ``` """ -function vrna_pf_fold(sequence, structure, pl) - ccall((:vrna_pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequence, structure, pl) +function vrna_plot_coords_pt(pt, x, y, plot_type) + ccall((:vrna_plot_coords_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Cint), pt, x, y, plot_type) end """ - vrna_pf_circfold(sequence, structure, pl) + vrna_plot_coords_simple(structure, x, y) - @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for a circular - RNA sequences using a comparative method + @brief Compute nucleotide coordinates for secondary structure plot the Simple way - This simplified interface to vrna_pf() computes the partition function and, if required, - base pair probabilities for a circular RNA sequence using default options. Memory required for - dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of - this function, the recursively filled matrices are not available any more for any post-processing. + This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_pf(), - and the data structure #vrna_fold_compound_t instead. + Here is a simple example how to use this function, assuming variable @p structure contains + a valid dot-bracket string: + @code{.c} + float *x, *y; - Folding of circular RNA sequences is handled as a post-processing step of the forward - recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. + if (vrna_plot_coords_simple(structure, &x, &y)) { + printf("all fine"); + } else { + printf("some failure occured!"); + } - @see vrna_pf_fold(), vrna_pf(), vrna_fold_compound(), #vrna_fold_compound_t + free(x); + free(y); + @endcode - @param sequence A circular RNA sequence - @param structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) - @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! + + @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_circular(), + vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() + + @param structure The secondary structure in dot-bracket notation + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -float vrna_pf_circfold(const char *sequence, char *structure, vrna_ep_t **pl); +int vrna_plot_coords_simple(const char *structure, float **x, float **y); ``` """ -function vrna_pf_circfold(sequence, structure, pl) - ccall((:vrna_pf_circfold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequence, structure, pl) +function vrna_plot_coords_simple(structure, x, y) + ccall((:vrna_plot_coords_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), structure, x, y) end """ - vrna_pf_alifold(sequences, structure, pl) + vrna_plot_coords_simple_pt(pt, x, y) - @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an RNA - sequence alignment using a comparative method + @brief Compute nucleotide coordinates for secondary structure plot the Simple way - This simplified interface to vrna_pf() computes the partition function and, if required, - base pair probabilities for an RNA sequence alignment using default options. Memory required for - dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of - this function, the recursively filled matrices are not available any more for any post-processing. + Same as vrna_plot_coords_simple() but takes a pair table with the structure + information as input. - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_pf(), - and the data structure #vrna_fold_compound_t instead. + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! - @see vrna_pf_circalifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t + @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_circular_pt(), + vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() - @param sequences RNA sequence alignment - @param structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) - @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol + @param pt The pair table that holds the secondary structure + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -float vrna_pf_alifold(const char **sequences, char *structure, vrna_ep_t **pl); +int vrna_plot_coords_simple_pt(const short *pt, float **x, float **y); ``` """ -function vrna_pf_alifold(sequences, structure, pl) - ccall((:vrna_pf_alifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequences, structure, pl) +function vrna_plot_coords_simple_pt(pt, x, y) + ccall((:vrna_plot_coords_simple_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), pt, x, y) end """ - vrna_pf_circalifold(sequences, structure, pl) + vrna_plot_coords_circular(structure, x, y) - @brief Compute Partition function @f\$Q@f\$ (and base pair probabilities) for an alignment - of circular RNA sequences using a comparative method + @brief Compute coordinates of nucleotides mapped in equal distancies onto a unit circle. - This simplified interface to vrna_pf() computes the partition function and, if required, - base pair probabilities for an RNA sequence alignment using default options. Memory required for - dynamic programming (DP) matrices will be allocated and free'd on-the-fly. Hence, after return of - this function, the recursively filled matrices are not available any more for any post-processing. + This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. - @note In case you want to use the filled DP matrices for any subsequent post-processing step, or - you require other conditions than specified by the default model details, use vrna_pf(), - and the data structure #vrna_fold_compound_t instead. + In order to draw nice arcs using quadratic bezier curves that connect base pairs one may calculate + a second tangential point @f\$P^t@f\$ in addition to the actual R2 coordinates. + the simplest way to do so may be to compute a radius scaling factor @f\$rs@f\$ in the interval @f\$[0,1]@f\$ that + weights the proportion of base pair span to the actual length of the sequence. This scaling factor + can then be used to calculate the coordinates for @f\$P^t@f\$, i.e. - Folding of circular RNA sequences is handled as a post-processing step of the forward - recursions. See @rstinline :cite:t:`hofacker:2006` @endrst for further details. + @f[ P^{t}_x[i] = X[i] * rs @f] - @see vrna_pf_alifold(), vrna_pf(), vrna_fold_compound_comparative(), #vrna_fold_compound_t + and - @param sequences Sequence alignment of circular RNAs - @param structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) - @return The ensemble free energy @f\$G = -RT \\cdot \\log(Q) @f\$ in kcal/mol + @f[ P^{t}_y[i] = Y[i] * rs @f]. + + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! + + @see vrna_plot_coords(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple(), + vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() + + @param structure The secondary structure in dot-bracket notation + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -float vrna_pf_circalifold(const char **sequences, char *structure, vrna_ep_t **pl); +int vrna_plot_coords_circular(const char *structure, float **x, float **y); ``` """ -function vrna_pf_circalifold(sequences, structure, pl) - ccall((:vrna_pf_circalifold, libRNA), Cfloat, (Ptr{Ptr{Cchar}}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), sequences, structure, pl) +function vrna_plot_coords_circular(structure, x, y) + ccall((:vrna_plot_coords_circular, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), structure, x, y) end """ - vrna_pf_co_fold(seq, structure, pl) + vrna_plot_coords_circular_pt(pt, x, y) - @brief Calculate partition function and base pair probabilities of - nucleic acid/nucleic acid dimers + @brief Compute nucleotide coordinates for a Circular Plot - This simplified interface to vrna_pf_dimer() computes the partition - function and, if required, base pair probabilities for an RNA-RNA - interaction using default options. Memory required for dynamic - programming (DP) matrices will be allocated and free'd on-the-fly. - Hence, after return of this function, the recursively filled matrices - are not available any more for any post-processing. + Same as vrna_plot_coords_circular() but takes a pair table with the structure + information as input. - @note In case you want to use the filled DP matrices for any subsequent - post-processing step, or you require other conditions than - specified by the default model details, use vrna_pf_dimer(), - and the data structure #vrna_fold_compound_t instead. + @note On success, this function allocates memory for X and Y coordinates and assigns + the pointers at addressess @p x and @p y to the corresponding memory locations. It's + the users responsibility to cleanup this memory after usage! - @see vrna_pf_dimer() + @see vrna_plot_coords_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple_pt(), + vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() - @ingroup pf_cofold - @param seq Two concatenated RNA sequences with a delimiting '&' in between - @param structure A pointer to the character array where position-wise pairing propensity - will be stored. (Maybe NULL) - @param pl A pointer to a list of #vrna_ep_t to store pairing probabilities (Maybe NULL) - @return vrna_dimer_pf_t structure containing a set of energies needed for - concentration computations. + @param pt The pair table that holds the secondary structure + @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) + @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) + @return The length of the structure on success, 0 otherwise ### Prototype ```c -vrna_dimer_pf_t vrna_pf_co_fold(const char *seq, char *structure, vrna_ep_t **pl); +int vrna_plot_coords_circular_pt(const short *pt, float **x, float **y); ``` """ -function vrna_pf_co_fold(seq, structure, pl) - ccall((:vrna_pf_co_fold, libRNA), vrna_dimer_pf_t, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Ptr{vrna_ep_t}}), seq, structure, pl) +function vrna_plot_coords_circular_pt(pt, x, y) + ccall((:vrna_plot_coords_circular_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), pt, x, y) end """ - vrna_pf_float_precision() + COORDINATE - @brief Find out whether partition function computations are using - single precision floating points + @brief this is a workarround for the SWIG Perl Wrapper RNA plot function + that returns an array of type COORDINATE +""" +struct COORDINATE + X::Cfloat + Y::Cfloat +end - @ingroup pf_fold +""" + simple_xy_coordinates(pair_table, X, Y) - @see #FLT_OR_DBL - @return 1 if single precision is used, 0 otherwise ### Prototype ```c -int vrna_pf_float_precision(void); +; ``` """ -function vrna_pf_float_precision() - ccall((:vrna_pf_float_precision, libRNA), Cint, ()) +function simple_xy_coordinates(pair_table, X, Y) + ccall((:simple_xy_coordinates, libRNA), Cint, (Ptr{Cshort}, Ptr{Cfloat}, Ptr{Cfloat}), pair_table, X, Y) end """ - pf_fold_par(sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) + simple_circplot_coordinates(pair_table, x, y) ### Prototype @@ -10229,64 +10478,140 @@ end ; ``` """ -function pf_fold_par(sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) - ccall((:pf_fold_par, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_exp_param_t}, Cint, Cint, Cint), sequence, structure, parameters, calculate_bppm, is_constrained, is_circular) +function simple_circplot_coordinates(pair_table, x, y) + ccall((:simple_circplot_coordinates, libRNA), Cint, (Ptr{Cshort}, Ptr{Cfloat}, Ptr{Cfloat}), pair_table, x, y) end """ - pf_fold(sequence, structure) - + vrna_subopt_sol_s -### Prototype -```c -; -``` + @brief Solution element from subopt.c """ -function pf_fold(sequence, structure) - ccall((:pf_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) +struct vrna_subopt_sol_s + energy::Cfloat + structure::Ptr{Cchar} end """ - pf_circ_fold(sequence, structure) + @brief Typename for the subopt solution list repesenting data structure #vrna_subopt_sol_s +""" +const vrna_subopt_solution_t = vrna_subopt_sol_s + +# typedef void ( * vrna_subopt_result_f ) ( const char * stucture , float energy , void * data ) +""" + @brief Callback for vrna_subopt_cb() + @ingroup subopt_wuchty +@callback +@parblock +This function will be called for each suboptimal secondary structure that is successfully backtraced. +@endparblock -### Prototype -```c -; -``` +@see vrna_subopt_cb() + +@param structure The suboptimal secondary structure in dot-bracket notation +@param energy The free energy of the secondary structure in kcal/mol +@param data Some arbitrary, auxiliary data address as passed to vrna_subopt_cb() """ -function pf_circ_fold(sequence, structure) - ccall((:pf_circ_fold, libRNA), Cfloat, (Ptr{Cchar}, Ptr{Cchar}), sequence, structure) -end +const vrna_subopt_result_f = Ptr{Cvoid} + +# DEPRECATED +const vrna_subopt_callback = Cvoid """ - pbacktrack(sequence) + @brief Backward compatibility typedef for #vrna_subopt_sol_s + @deprecated Use #vrna_subopt_solution_t instead! +""" +const SOLUTION = vrna_subopt_sol_s + +""" + vrna_subopt(fc, delta, sorted, fp) + + @brief Returns list of subopt structures or writes to fp + + This function produces all suboptimal secondary structures within + 'delta' * 0.01 kcal/mol of the optimum, see @rstinline :cite:t:`wuchty:1999` @endrst. The results + are either directly written to a 'fp' (if 'fp' is not NULL), or + (fp==NULL) returned in a #vrna_subopt_solution_t * list terminated + by an entry were the 'structure' member is NULL. + + @ingroup subopt_wuchty + + @note This function requires all multibranch loop DP matrices for unique + multibranch loop backtracing. Therefore, the supplied #vrna_fold_compound_t + @p fc (argument 1) must be initialized with #vrna_md_t.uniq_ML = 1, for + instance like this: + @code +vrna_md_t md; +vrna_md_set_default(&md); +md.uniq_ML = 1; + +vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT); + @endcode + @see vrna_subopt_cb(), vrna_subopt_zuker() + @param fc + @param delta + @param sorted Sort results by energy in ascending order + @param fp + @return ### Prototype ```c -; +vrna_subopt_solution_t * vrna_subopt(vrna_fold_compound_t *fc, int delta, int sorted, FILE *fp); ``` """ -function pbacktrack(sequence) - ccall((:pbacktrack, libRNA), Ptr{Cchar}, (Ptr{Cchar},), sequence) +function vrna_subopt(fc, delta, sorted, fp) + ccall((:vrna_subopt, libRNA), Ptr{vrna_subopt_solution_t}, (Ptr{vrna_fold_compound_t}, Cint, Cint, Ptr{Libc.FILE}), fc, delta, sorted, fp) end """ - pbacktrack5(sequence, length) + vrna_subopt_cb(fc, delta, cb, data) + + @brief Generate suboptimal structures within an energy band arround the MFE + + This is the most generic implementation of the suboptimal structure generator + according to @rstinline :cite:t:`wuchty:1999` @endrst. Identical to vrna_subopt(), it computes all + secondary structures within an energy band @p delta arround the MFE. However, + this function does not print the resulting structures and their corresponding + free energies to a file pointer, or returns them as a list. Instead, it calls + a user-provided callback function which it passes the structure in dot-bracket + format, the corresponding free energy in kcal/mol, and a user-provided data + structure each time a structure was backtracked successfully. This function + indicates the final output, i.e. the end of the backtracking procedure by + passing NULL instead of an actual dot-bracket string to the callback. + @ingroup subopt_wuchty + + @note This function requires all multibranch loop DP matrices for unique + multibranch loop backtracing. Therefore, the supplied #vrna_fold_compound_t + @p fc (argument 1) must be initialized with #vrna_md_t.uniq_ML = 1, for + instance like this: + @code +vrna_md_t md; +vrna_md_set_default(&md); +md.uniq_ML = 1; + +vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT); + @endcode + + @see vrna_subopt_result_f, vrna_subopt(), vrna_subopt_zuker() + @param fc fold compount with the sequence data + @param delta Energy band arround the MFE in 10cal/mol, i.e. deka-calories + @param cb Pointer to a callback function that handles the backtracked structure and its free energy in kcal/mol + @param data Pointer to some data structure that is passed along to the callback ### Prototype ```c -; +void vrna_subopt_cb(vrna_fold_compound_t *fc, int delta, vrna_subopt_result_f cb, void *data); ``` """ -function pbacktrack5(sequence, length) - ccall((:pbacktrack5, libRNA), Ptr{Cchar}, (Ptr{Cchar}, Cint), sequence, length) +function vrna_subopt_cb(fc, delta, cb, data) + ccall((:vrna_subopt_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, vrna_subopt_result_f, Ptr{Cvoid}), fc, delta, cb, data) end """ - pbacktrack_circ(sequence) + subopt(seq, structure, delta, fp) ### Prototype @@ -10294,12 +10619,12 @@ end ; ``` """ -function pbacktrack_circ(sequence) - ccall((:pbacktrack_circ, libRNA), Ptr{Cchar}, (Ptr{Cchar},), sequence) +function subopt(seq, structure, delta, fp) + ccall((:subopt, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), seq, structure, delta, fp) end """ - free_pf_arrays() + subopt_par(seq, structure, parameters, delta, is_constrained, is_circular, fp) ### Prototype @@ -10307,12 +10632,12 @@ end ; ``` """ -function free_pf_arrays() - ccall((:free_pf_arrays, libRNA), Cvoid, ()) +function subopt_par(seq, structure, parameters, delta, is_constrained, is_circular, fp) + ccall((:subopt_par, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint, Cint, Cint, Ptr{Libc.FILE}), seq, structure, parameters, delta, is_constrained, is_circular, fp) end """ - update_pf_params(length) + subopt_circ(seq, sequence, delta, fp) ### Prototype @@ -10320,12 +10645,12 @@ end ; ``` """ -function update_pf_params(length) - ccall((:update_pf_params, libRNA), Cvoid, (Cint,), length) +function subopt_circ(seq, sequence, delta, fp) + ccall((:subopt_circ, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), seq, sequence, delta, fp) end """ - update_pf_params_par(length, parameters) + zukersubopt(string) ### Prototype @@ -10333,12 +10658,12 @@ end ; ``` """ -function update_pf_params_par(length, parameters) - ccall((:update_pf_params_par, libRNA), Cvoid, (Cint, Ptr{vrna_exp_param_t}), length, parameters) +function zukersubopt(string) + ccall((:zukersubopt, libRNA), Ptr{SOLUTION}, (Ptr{Cchar},), string) end """ - export_bppm() + zukersubopt_par(string, parameters) ### Prototype @@ -10346,998 +10671,967 @@ end ; ``` """ -function export_bppm() - ccall((:export_bppm, libRNA), Ptr{FLT_OR_DBL}, ()) +function zukersubopt_par(string, parameters) + ccall((:zukersubopt_par, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{vrna_param_t}), string, parameters) end """ - get_pf_arrays(S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) + vrna_subopt_zuker(fc) + + @brief Compute Zuker type suboptimal structures + + Compute Suboptimal structures according to @rstinline :cite:t:`zuker:1989` @endrst , i.e. for every + possible base pair the minimum energy structure containing the resp. base pair. + Returns a list of these structures and their energies. + + @ingroup subopt_zuker + @see vrna_subopt(), zukersubopt(), zukersubopt_par() + @param fc fold compound + @return List of zuker suboptimal structures ### Prototype ```c -; +vrna_subopt_solution_t * vrna_subopt_zuker(vrna_fold_compound_t *fc); ``` """ -function get_pf_arrays(S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) - ccall((:get_pf_arrays, libRNA), Cint, (Ptr{Ptr{Cshort}}, Ptr{Ptr{Cshort}}, Ptr{Ptr{Cchar}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}, Ptr{Ptr{FLT_OR_DBL}}), S_p, S1_p, ptype_p, qb_p, qm_p, q1k_p, qln_p) +function vrna_subopt_zuker(fc) + ccall((:vrna_subopt_zuker, libRNA), Ptr{vrna_subopt_solution_t}, (Ptr{vrna_fold_compound_t},), fc) end """ - get_subseq_F(i, j) + Postorder_list + + @brief Postorder data structure +""" +struct Postorder_list + type::Cint + weight::Cint + father::Cint + sons::Cint + leftmostleaf::Cint +end +""" + Tree -### Prototype -```c -; -``` + @brief Tree data structure """ -function get_subseq_F(i, j) - ccall((:get_subseq_F, libRNA), Cdouble, (Cint, Cint), i, j) +struct Tree + postorder_list::Ptr{Postorder_list} + keyroots::Ptr{Cint} end """ - mean_bp_distance(length) + swString + + @brief Some other data structure +""" +struct swString + type::Cint + sign::Cint + weight::Cfloat +end +""" + make_tree(struc) + + \\brief Constructs a Tree ( essentially the postorder list ) of the + structure 'struc', for use in tree_edit_distance(). + \\param struc may be any rooted structure representation. + \\return ### Prototype ```c -; +Tree *make_tree(char *struc); ``` """ -function mean_bp_distance(length) - ccall((:mean_bp_distance, libRNA), Cdouble, (Cint,), length) +function make_tree(struc) + ccall((:make_tree, libRNA), Ptr{Tree}, (Ptr{Cchar},), struc) end """ - mean_bp_distance_pr(length, pr) + tree_edit_distance(T1, T2) + \\brief Calculates the edit distance of the two trees. + \\param T1 + \\param T2 + \\return ### Prototype ```c -; +float tree_edit_distance(Tree *T1, Tree *T2); ``` """ -function mean_bp_distance_pr(length, pr) - ccall((:mean_bp_distance_pr, libRNA), Cdouble, (Cint, Ptr{FLT_OR_DBL}), length, pr) +function tree_edit_distance(T1, T2) + ccall((:tree_edit_distance, libRNA), Cfloat, (Ptr{Tree}, Ptr{Tree}), T1, T2) end """ - stackProb(cutoff) - + print_tree(t) + \\brief Print a tree (mainly for debugging) ### Prototype ```c -; +void print_tree(Tree *t); ``` """ -function stackProb(cutoff) - ccall((:stackProb, libRNA), Ptr{vrna_ep_t}, (Cdouble,), cutoff) +function print_tree(t) + ccall((:print_tree, libRNA), Cvoid, (Ptr{Tree},), t) end """ - init_pf_fold(length) + free_tree(t) + \\brief Free the memory allocated for Tree t. + \\param t ### Prototype ```c -; +void free_tree(Tree *t); ``` """ -function init_pf_fold(length) - ccall((:init_pf_fold, libRNA), Cvoid, (Cint,), length) +function free_tree(t) + ccall((:free_tree, libRNA), Cvoid, (Ptr{Tree},), t) end """ - centroid(length, dist) + vrna_alloc(size) + @brief Allocate space safely + @param size The size of the memory to be allocated in bytes + @return A pointer to the allocated memory ### Prototype ```c -; +void * vrna_alloc(unsigned size); ``` """ -function centroid(length, dist) - ccall((:centroid, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}), length, dist) +function vrna_alloc(size) + ccall((:vrna_alloc, libRNA), Ptr{Cvoid}, (Cuint,), size) end """ - get_centroid_struct_gquad_pr(length, dist) + vrna_realloc(p, size) + @brief Reallocate space safely + @param p A pointer to the memory region to be reallocated + @param size The size of the memory to be allocated in bytes + @return A pointer to the newly allocated memory ### Prototype ```c -; +void * vrna_realloc(void *p, unsigned size); ``` """ -function get_centroid_struct_gquad_pr(length, dist) - ccall((:get_centroid_struct_gquad_pr, libRNA), Ptr{Cchar}, (Cint, Ptr{Cdouble}), length, dist) +function vrna_realloc(p, size) + ccall((:vrna_realloc, libRNA), Ptr{Cvoid}, (Ptr{Cvoid}, Cuint), p, size) end """ - mean_bp_dist(length) + vrna_init_rand() + @brief Initialize seed for random number generator + @see vrna_init_rand_seed(), vrna_urn() ### Prototype ```c -; +void vrna_init_rand(void); ``` """ -function mean_bp_dist(length) - ccall((:mean_bp_dist, libRNA), Cdouble, (Cint,), length) +function vrna_init_rand() + ccall((:vrna_init_rand, libRNA), Cvoid, ()) end """ - expLoopEnergy(u1, u2, type, type2, si1, sj1, sp1, sq1) + vrna_init_rand_seed(seed) + @brief Initialize the random number generator with a pre-defined seed + + @see vrna_init_rand(), vrna_urn() + @param seed The seed for the random number generator ### Prototype ```c -; +void vrna_init_rand_seed(unsigned int seed); ``` """ -function expLoopEnergy(u1, u2, type, type2, si1, sj1, sp1, sq1) - ccall((:expLoopEnergy, libRNA), Cdouble, (Cint, Cint, Cint, Cint, Cshort, Cshort, Cshort, Cshort), u1, u2, type, type2, si1, sj1, sp1, sq1) +function vrna_init_rand_seed(seed) + ccall((:vrna_init_rand_seed, libRNA), Cvoid, (Cuint,), seed) end """ - expHairpinEnergy(u, type, si1, sj1, string) + vrna_urn() + @brief get a random number from [0..1] + + @note Usually implemented by calling @e erand48(). + + @see vrna_int_urn(), vrna_init_rand(), vrna_init_rand_seed() + @return A random number in range [0..1] ### Prototype ```c -; +double vrna_urn(void); ``` """ -function expHairpinEnergy(u, type, si1, sj1, string) - ccall((:expHairpinEnergy, libRNA), Cdouble, (Cint, Cint, Cshort, Cshort, Ptr{Cchar}), u, type, si1, sj1, string) +function vrna_urn() + ccall((:vrna_urn, libRNA), Cdouble, ()) end """ - assign_plist_gquad_from_pr(pl, length, cut_off) + vrna_int_urn(from, to) + + @brief Generates a pseudo random integer in a specified range + @see vrna_urn(), vrna_init_rand() + @param from The first number in range + @param to The last number in range + @return A pseudo random number in range [from, to] ### Prototype ```c -; +int vrna_int_urn(int from, int to); ``` """ -function assign_plist_gquad_from_pr(pl, length, cut_off) - ccall((:assign_plist_gquad_from_pr, libRNA), Cvoid, (Ptr{Ptr{vrna_ep_t}}, Cint, Cdouble), pl, length, cut_off) +function vrna_int_urn(from, to) + ccall((:vrna_int_urn, libRNA), Cint, (Cint, Cint), from, to) end -# typedef void ( * vrna_probs_window_f ) ( FLT_OR_DBL * pr , int pr_size , int i , int max , unsigned int type , void * data ) """ -@brief Sliding window probability computation callback - -@callback -@parblock -This function will be called for each probability data set in the sliding -window probability computation implementation of vrna_probs_window(). -The argument @a type specifies the type of probability that is passed to -this function. -@endparblock + vrna_time_stamp() -#### Types: #### - * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP - * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP - * #VRNA_PROBS_WINDOW_PF - @copybrief #VRNA_PROBS_WINDOW_PF + @brief Get a timestamp -The above types usually come exclusively. However, for unpaired -probabilities, the #VRNA_PROBS_WINDOW_UP flag is OR-ed together -with one of the loop type contexts + Returns a string containing the current date in the format + @verbatim Fri Mar 19 21:10:57 1993 @endverbatim - * #VRNA_EXT_LOOP - @copybrief #VRNA_EXT_LOOP - * #VRNA_HP_LOOP - @copybrief #VRNA_HP_LOOP - * #VRNA_INT_LOOP - @copybrief #VRNA_INT_LOOP - * #VRNA_MB_LOOP - @copybrief #VRNA_MB_LOOP - * #VRNA_ANY_LOOP - @copybrief #VRNA_ANY_LOOP + @return A string containing the timestamp +### Prototype +```c +char * vrna_time_stamp(void); +``` +""" +function vrna_time_stamp() + ccall((:vrna_time_stamp, libRNA), Ptr{Cchar}, ()) +end -to indicate the particular type of data available through the @p pr -pointer. +""" + get_input_line(string, options) -@see vrna_probs_window(), vrna_pfl_fold_up_cb() + 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 one to switch between different reading modes.\\n + Currently available options are:\\n + #VRNA_INPUT_COMMENT, #VRNA_INPUT_NOSKIP_COMMENTS, #VRNA_INPUT_NO_TRUNCATION -@param pr An array of probabilities -@param pr_size The length of the probability array -@param i The i-position (5') of the probabilities -@param max The (theoretical) maximum length of the probability array -@param type The type of data that is provided -@param data Auxiliary data -""" -const vrna_probs_window_f = Ptr{Cvoid} + pass a collection of options as one value like this: + @verbatim get_input_line(string, option_1 | option_2 | option_n) @endverbatim -# DEPRECATED -const vrna_probs_window_callback = Cvoid + 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:\\n + #VRNA_INPUT_FASTA_HEADER, #VRNA_INPUT_ERROR, #VRNA_INPUT_MISC, #VRNA_INPUT_QUIT + @param string A pointer to the character array that contains the line read + @param options A collection of options for switching the functions behavior + @return A flag with information about what has been read +### Prototype +```c +unsigned int get_input_line(char **string, unsigned int options); +``` """ - vrna_probs_window(fc, ulength, options, cb, data) - - @brief Compute various equilibrium probabilities under a sliding window approach +function get_input_line(string, options) + ccall((:get_input_line, libRNA), Cuint, (Ptr{Ptr{Cchar}}, Cuint), string, options) +end - This function applies a sliding window scan for the sequence provided with the - argument @p fc and reports back equilibrium probabilities through the callback - function @p cb. The data reported to the callback depends on the @p options flag. +""" + vrna_idx_row_wise(length) - @note The parameter @p ulength only affects computation and resulting data if unpaired - probability computations are requested through the @p options flag. + @brief Get an index mapper array (iindx) for accessing the energy matrices, e.g. in partition function related functions. - #### Options: #### - * #VRNA_PROBS_WINDOW_BPP - @copybrief #VRNA_PROBS_WINDOW_BPP - * #VRNA_PROBS_WINDOW_UP - @copybrief #VRNA_PROBS_WINDOW_UP - * #VRNA_PROBS_WINDOW_UP_SPLIT - @copybrief #VRNA_PROBS_WINDOW_UP_SPLIT + Access of a position "(i,j)" is then accomplished by using @verbatim (i,j) ~ iindx[i]-j @endverbatim + This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout + the ViennaRNA Package - Options may be OR-ed together + Consult the implemented code to find out about the mapping formula ;) - @see vrna_pfl_fold_cb(), vrna_pfl_fold_up_cb() + @see vrna_idx_col_wise() - @param fc The fold compound with sequence data, model settings and precomputed energy parameters - @param ulength The maximal length of an unpaired segment (only for unpaired probability computations) - @param cb The callback function which collects the pair probability data for further processing - @param data Some arbitrary data structure that is passed to the callback @p cb - @param options Option flags to control the behavior of this function - @return 0 on failure, non-zero on success + @param length The length of the RNA sequence + @return The mapper array ### Prototype ```c -int vrna_probs_window(vrna_fold_compound_t *fc, int ulength, unsigned int options, vrna_probs_window_f cb, void *data); +int * vrna_idx_row_wise(unsigned int length); ``` """ -function vrna_probs_window(fc, ulength, options, cb, data) - ccall((:vrna_probs_window, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cuint, vrna_probs_window_f, Ptr{Cvoid}), fc, ulength, options, cb, data) +function vrna_idx_row_wise(length) + ccall((:vrna_idx_row_wise, libRNA), Ptr{Cint}, (Cuint,), length) end """ - vrna_pfl_fold(sequence, window_size, max_bp_span, cutoff) + vrna_idx_col_wise(length) - @brief Compute base pair probabilities using a sliding-window approach + @brief Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions. - This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, - a window size, a maximum base pair span, and a cutoff value computes the pair probabilities - for any base pair in any window. The pair probabilities are returned as a list and the user - has to take care to free() the memory occupied by the list. + Access of a position "(i,j)" is then accomplished by using @verbatim (i,j) ~ indx[j]+i @endverbatim + This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout + the ViennaRNAPackage - @note This function uses default model settings! For custom model settings, we refer to - the function vrna_probs_window().
- In case of any computation errors, this function returns @p NULL + Consult the implemented code to find out about the mapping formula ;) - @see vrna_probs_window(), vrna_pfl_fold_cb(), vrna_pfl_fold_up() + @see vrna_idx_row_wise() + + @param length The length of the RNA sequence + @return The mapper array - @param sequence The nucleic acid input sequence - @param window_size The size of the sliding window - @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs - @param cutoff A cutoff value that omits all pairs with lower probability - @return A list of base pair probabilities, terminated by an entry with #vrna_ep_t.i and #vrna_ep_t.j set to 0 ### Prototype ```c -vrna_ep_t * vrna_pfl_fold(const char *sequence, int window_size, int max_bp_span, float cutoff); +int * vrna_idx_col_wise(unsigned int length); ``` """ -function vrna_pfl_fold(sequence, window_size, max_bp_span, cutoff) - ccall((:vrna_pfl_fold, libRNA), Ptr{vrna_ep_t}, (Ptr{Cchar}, Cint, Cint, Cfloat), sequence, window_size, max_bp_span, cutoff) +function vrna_idx_col_wise(length) + ccall((:vrna_idx_col_wise, libRNA), Ptr{Cint}, (Cuint,), length) end """ - vrna_pfl_fold_cb(sequence, window_size, max_bp_span, cb, data) + vrna_message_input_seq_simple() - @brief Compute base pair probabilities using a sliding-window approach (callback version) + @brief Print a line to @e stdout that asks for an input sequence - This is a simplified wrapper to vrna_probs_window() that given a nucleid acid sequence, - a window size, a maximum base pair span, and a cutoff value computes the pair probabilities - for any base pair in any window. It is similar to vrna_pfl_fold() but uses a callback mechanism - to return the pair probabilities. + There will also be a ruler (scale line) printed that helps orientation of the sequence positions +### Prototype +```c +void vrna_message_input_seq_simple(void); +``` +""" +function vrna_message_input_seq_simple() + ccall((:vrna_message_input_seq_simple, libRNA), Cvoid, ()) +end - Read the details for vrna_probs_window() for details on the callback implementation! +""" + vrna_message_input_seq(s) - @note This function uses default model settings! For custom model settings, we refer to - the function vrna_probs_window(). + @brief Print a line with a user defined string and a ruler to stdout. - @see vrna_probs_window(), vrna_pfl_fold(), vrna_pfl_fold_up_cb() + (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 - @param sequence The nucleic acid input sequence - @param window_size The size of the sliding window - @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs - @param cb The callback function which collects the pair probability data for further processing - @param data Some arbitrary data structure that is passed to the callback @p cb - @return 0 on failure, non-zero on success + @param s A user defined string that will be printed to stdout ### Prototype ```c -int vrna_pfl_fold_cb(const char *sequence, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data); +void vrna_message_input_seq(const char *s); ``` """ -function vrna_pfl_fold_cb(sequence, window_size, max_bp_span, cb, data) - ccall((:vrna_pfl_fold_cb, libRNA), Cint, (Ptr{Cchar}, Cint, Cint, vrna_probs_window_f, Ptr{Cvoid}), sequence, window_size, max_bp_span, cb, data) +function vrna_message_input_seq(s) + ccall((:vrna_message_input_seq, libRNA), Cvoid, (Ptr{Cchar},), s) end """ - vrna_pfl_fold_up(sequence, ulength, window_size, max_bp_span) + vrna_message_input_msa(s) - @brief Compute probability of contiguous unpaired segments - This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, - a maximum length of unpaired segments (@p ulength), a window size, and a maximum base - pair span computes the equilibrium probability of any segment not exceeding @p ulength. - The probabilities to be unpaired are returned as a 1-based, 2-dimensional matrix with - dimensions @f\$ N \\times M @f\$, where @f\$N@f\$ is the length of the sequence and @f\$M@f\$ - is the maximum segment length. As an example, the probability of a segment of size 5 - starting at position 100 is stored in the matrix entry @f\$X[100][5]@f\$. +### Prototype +```c +void vrna_message_input_msa(const char *s); +``` +""" +function vrna_message_input_msa(s) + ccall((:vrna_message_input_msa, libRNA), Cvoid, (Ptr{Cchar},), s) +end - It is the users responsibility to free the memory occupied by this matrix. +""" + get_indx(length) - @note This function uses default model settings! For custom model settings, we refer to - the function vrna_probs_window(). - @param sequence The nucleic acid input sequence - @param ulength The maximal length of an unpaired segment - @param window_size The size of the sliding window - @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs - @return The probabilities to be unpaired for any segment not exceeding @p ulength ### Prototype ```c -double ** vrna_pfl_fold_up(const char *sequence, int ulength, int window_size, int max_bp_span); +; ``` """ -function vrna_pfl_fold_up(sequence, ulength, window_size, max_bp_span) - ccall((:vrna_pfl_fold_up, libRNA), Ptr{Ptr{Cdouble}}, (Ptr{Cchar}, Cint, Cint, Cint), sequence, ulength, window_size, max_bp_span) +function get_indx(length) + ccall((:get_indx, libRNA), Ptr{Cint}, (Cuint,), length) end """ - vrna_pfl_fold_up_cb(sequence, ulength, window_size, max_bp_span, cb, data) - - @brief Compute probability of contiguous unpaired segments + get_iindx(length) - This is a simplified wrapper to vrna_probs_window() that given a nucleic acid sequence, - a maximum length of unpaired segments (@p ulength), a window size, and a maximum base - pair span computes the equilibrium probability of any segment not exceeding @p ulength. - It is similar to vrna_pfl_fold_up() but uses a callback mechanism to return the unpaired - probabilities. - Read the details for vrna_probs_window() for details on the callback implementation! +### Prototype +```c +; +``` +""" +function get_iindx(length) + ccall((:get_iindx, libRNA), Ptr{Cint}, (Cuint,), length) +end +""" + get_line(fp) - @note This function uses default model settings! For custom model settings, we refer to - the function vrna_probs_window(). - @param sequence The nucleic acid input sequence - @param ulength The maximal length of an unpaired segment - @param window_size The size of the sliding window - @param max_bp_span The maximum distance along the backbone between two nucleotides that form a base pairs - @param cb The callback function which collects the pair probability data for further processing - @param data Some arbitrary data structure that is passed to the callback @p cb - @return 0 on failure, non-zero on success ### Prototype ```c -int vrna_pfl_fold_up_cb(const char *sequence, int ulength, int window_size, int max_bp_span, vrna_probs_window_f cb, void *data); +; ``` """ -function vrna_pfl_fold_up_cb(sequence, ulength, window_size, max_bp_span, cb, data) - ccall((:vrna_pfl_fold_up_cb, libRNA), Cint, (Ptr{Cchar}, Cint, Cint, Cint, vrna_probs_window_f, Ptr{Cvoid}), sequence, ulength, window_size, max_bp_span, cb, data) -end - -struct vrna_plot_layout_s - length::Cuint - x::Ptr{Cfloat} - y::Ptr{Cfloat} - arcs::Ptr{Cdouble} - bbox::NTuple{4, Cint} +function get_line(fp) + ccall((:get_line, libRNA), Ptr{Cchar}, (Ptr{Libc.FILE},), fp) end """ - @brief RNA secondary structure figure layout + print_tty_input_seq() - @see vrna_plot_layout(), vrna_plot_layout_free(), vrna_plot_layout_simple(), - vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), - vrna_plot_layout_puzzler() -""" -const vrna_plot_layout_t = vrna_plot_layout_s +### Prototype +```c +; +``` """ - vrna_plot_coords_turtle(structure, x, y, arc_coords) +function print_tty_input_seq() + ccall((:print_tty_input_seq, libRNA), Cvoid, ()) +end - @brief Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst +""" + print_tty_input_seq_str(s) - This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_TURTLE. - Here is a simple example how to use this function, assuming variable @p structure contains - a valid dot-bracket string: - @code{.c} - float *x, *y; - double *arcs; +### Prototype +```c +; +``` +""" +function print_tty_input_seq_str(s) + ccall((:print_tty_input_seq_str, libRNA), Cvoid, (Ptr{Cchar},), s) +end - if (vrna_plot_coords_turtle(structure, &x, &y, &arcs)) { - printf("all fine"); - } else { - printf("some failure occured!"); - } +""" + warn_user(message) - free(x); - free(y); - free(arcs); - @endcode - @note On success, this function allocates memory for X, Y and arc coordinates and assigns - the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! +### Prototype +```c +; +``` +""" +function warn_user(message) + ccall((:warn_user, libRNA), Cvoid, (Ptr{Cchar},), message) +end + +""" + nrerror(message) - @see vrna_plot_coords(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_circular(), - vrna_plot_coords_simple(), vrna_plot_coords_naview(), vrna_plot_coords_puzzler() - @param structure The secondary structure in dot-bracket notation - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords_turtle(const char *structure, float **x, float **y, double **arc_coords); +; ``` """ -function vrna_plot_coords_turtle(structure, x, y, arc_coords) - ccall((:vrna_plot_coords_turtle, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}), structure, x, y, arc_coords) +function nrerror(message) + ccall((:nrerror, libRNA), Cvoid, (Ptr{Cchar},), message) end """ - vrna_plot_coords_turtle_pt(pair_table, x, y, arc_coords) - - @brief Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - - Same as vrna_plot_coords_turtle() but takes a pair table with the structure - information as input. - - @note On success, this function allocates memory for X, Y and arc coordinates and assigns - the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! + space(size) - @see vrna_plot_coords_pt(), vrna_plot_coords_turtle(), vrna_plot_coords_circular_pt(), - vrna_plot_coords_simple_pt(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_naview_pt() - @param pt The pair table that holds the secondary structure - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords_turtle_pt(short const *const pair_table, float **x, float **y, double **arc_coords); +; ``` """ -function vrna_plot_coords_turtle_pt(pair_table, x, y, arc_coords) - ccall((:vrna_plot_coords_turtle_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}), pair_table, x, y, arc_coords) +function space(size) + ccall((:space, libRNA), Ptr{Cvoid}, (Cuint,), size) end """ - vrna_plot_options_puzzler_t + xrealloc(p, size) - @brief Options data structure for RNApuzzler algorithm implementation + +### Prototype +```c +; +``` """ -struct vrna_plot_options_puzzler_t - drawArcs::Cshort - paired::Cdouble - unpaired::Cdouble - checkAncestorIntersections::Cshort - checkSiblingIntersections::Cshort - checkExteriorIntersections::Cshort - allowFlipping::Cshort - optimize::Cshort - maximumNumberOfConfigChangesAllowed::Cint - config::Ptr{Cchar} - filename::Ptr{Cchar} - numberOfChangesAppliedToConfig::Cint - psNumber::Cint +function xrealloc(p, size) + ccall((:xrealloc, libRNA), Ptr{Cvoid}, (Ptr{Cvoid}, Cuint), p, size) end """ - vrna_plot_coords_puzzler(structure, x, y, arc_coords, options) - - @brief Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - - This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_PUZZLER. - - Here is a simple example how to use this function, assuming variable @p structure contains - a valid dot-bracket string and using the default options (@p options = NULL): - @code{.c} - float *x, *y; - double *arcs; + init_rand() - if (vrna_plot_coords_puzzler(structure, &x, &y, &arcs, NULL)) { - printf("all fine"); - } else { - printf("some failure occured!"); - } - free(x); - free(y); - free(arcs); - @endcode +### Prototype +```c +; +``` +""" +function init_rand() + ccall((:init_rand, libRNA), Cvoid, ()) +end - @note On success, this function allocates memory for X, Y and arc coordinates and assigns - the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! +""" + urn() - @see vrna_plot_coords(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_circular(), - vrna_plot_coords_simple(), vrna_plot_coords_turtle(), vrna_plot_coords_naview(), - vrna_plot_options_puzzler() - @param structure The secondary structure in dot-bracket notation - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) - @param options The options for the RNApuzzler algorithm (or NULL) - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords_puzzler(const char *structure, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *options); +; ``` """ -function vrna_plot_coords_puzzler(structure, x, y, arc_coords, options) - ccall((:vrna_plot_coords_puzzler, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}, Ptr{vrna_plot_options_puzzler_t}), structure, x, y, arc_coords, options) +function urn() + ccall((:urn, libRNA), Cdouble, ()) end """ - vrna_plot_coords_puzzler_pt(pair_table, x, y, arc_coords, puzzler) + int_urn(from, to) - @brief Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - Same as vrna_plot_coords_puzzler() but takes a pair table with the structure - information as input. +### Prototype +```c +; +``` +""" +function int_urn(from, to) + ccall((:int_urn, libRNA), Cint, (Cint, Cint), from, to) +end - @note On success, this function allocates memory for X, Y and arc coordinates and assigns - the pointers at addressess @p x, @p y and @p arc_coords to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! +""" + filecopy(from, to) - @see vrna_plot_coords_pt(), vrna_plot_coords_puzzler(), vrna_plot_coords_circular_pt(), - vrna_plot_coords_simple_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_naview_pt() - @param pt The pair table that holds the secondary structure - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param[inout] arc_coords The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure) - @param options The options for the RNApuzzler algorithm (or NULL) - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords_puzzler_pt(short const *const pair_table, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *puzzler); +; ``` """ -function vrna_plot_coords_puzzler_pt(pair_table, x, y, arc_coords, puzzler) - ccall((:vrna_plot_coords_puzzler_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cdouble}}, Ptr{vrna_plot_options_puzzler_t}), pair_table, x, y, arc_coords, puzzler) +function filecopy(from, to) + ccall((:filecopy, libRNA), Cvoid, (Ptr{Libc.FILE}, Ptr{Libc.FILE}), from, to) end """ - vrna_plot_options_puzzler() - - @brief Create an RNApuzzler options data structure + time_stamp() - @see vrna_plot_options_puzzler_free(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), - vrna_plot_layout_puzzler() - @return An RNApuzzler options data structure with default settings ### Prototype ```c -vrna_plot_options_puzzler_t * vrna_plot_options_puzzler(void); +; ``` """ -function vrna_plot_options_puzzler() - ccall((:vrna_plot_options_puzzler, libRNA), Ptr{vrna_plot_options_puzzler_t}, ()) +function time_stamp() + ccall((:time_stamp, libRNA), Ptr{Cchar}, ()) end """ - vrna_plot_options_puzzler_free(options) + vrna_constraints_add(fc, constraint, options) - @brief Free memory occupied by an RNApuzzler options data structure + @brief Add constraints to a #vrna_fold_compound_t data structure - @see vrna_plot_options_puzzler(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), - vrna_plot_layout_puzzler() + Use this function to add/update the hard/soft constraints + The function allows for passing a string 'constraint' that can either be a + filename that points to a constraints definition file or it may be a + pseudo dot-bracket notation indicating hard constraints. For the latter, the + user has to pass the #VRNA_CONSTRAINT_DB option. Also, the + user has to specify, which characters are allowed to be interpreted as + constraints by passing the corresponding options via the third parameter. - @param options A pointer to the options data structure to free + @ingroup hard_constraints + + The following is an example for adding hard constraints given in + pseudo dot-bracket notation. Here, @p fc is the #vrna_fold_compound_t object, + @p structure is a char array with the hard constraint in dot-bracket notation, + and @p enforceConstraints is a flag indicating whether or not constraints for + base pairs should be enforced instead of just doing a removal of base pair that + conflict with the constraint. + + @snippet RNAfold.c Adding hard constraints from pseudo dot-bracket + + In constrat to the above, constraints may also be read from file: + + @snippet RNAfold.c Adding hard constraints from file + + @see vrna_hc_add_from_db(), vrna_hc_add_up(), vrna_hc_add_up_batch() + vrna_hc_add_bp_unspecific(), vrna_hc_add_bp(), + vrna_hc_init(), vrna_sc_set_up(), vrna_sc_set_bp(), + vrna_sc_add_SHAPE_deigan(), vrna_sc_add_SHAPE_zarringhalam(), + vrna_hc_free(), vrna_sc_free(), + #VRNA_CONSTRAINT_DB, #VRNA_CONSTRAINT_DB_DEFAULT, #VRNA_CONSTRAINT_DB_PIPE, + #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, + #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTRAMOL, + #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_GQUAD + + @param fc The fold compound + @param constraint A string with either the filename of the constraint definitions + or a pseudo dot-bracket notation of the hard constraint. May be NULL. + @param options The option flags ### Prototype ```c -void vrna_plot_options_puzzler_free(vrna_plot_options_puzzler_t *options); +void vrna_constraints_add(vrna_fold_compound_t *fc, const char *constraint, unsigned int options); ``` """ -function vrna_plot_options_puzzler_free(options) - ccall((:vrna_plot_options_puzzler_free, libRNA), Cvoid, (Ptr{vrna_plot_options_puzzler_t},), options) +function vrna_constraints_add(fc, constraint, options) + ccall((:vrna_constraints_add, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cuint), fc, constraint, options) end """ - vrna_plot_layout(structure, plot_type) + vrna_hc_up_s - @brief Create a layout (coordinates, etc.) for a secondary structure plot + @brief A single hard constraint for a single nucleotide - This function can be used to create a secondary structure nucleotide layout - that is then further processed by an actual plotting function. The layout - algorithm can be specified using the @p plot_type parameter, and the following - algorithms are currently supported: - - #VRNA_PLOT_TYPE_SIMPLE - - #VRNA_PLOT_TYPE_NAVIEW - - #VRNA_PLOT_TYPE_CIRCULAR - - #VRNA_PLOT_TYPE_TURTLE - - #VRNA_PLOT_TYPE_PUZZLER + @ingroup hard_constraints +""" +struct vrna_hc_up_s + position::Cint + strand::Cint + options::Cuchar +end - Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW +""" + @brief Typename for the single nucleotide hard constraint data structure #vrna_hc_up_s + @ingroup hard_constraints +""" +const vrna_hc_up_t = vrna_hc_up_s - @note If only X-Y coordinates of the corresponding structure layout are required, consider - using vrna_plot_coords() instead! +# DEPRECATED +const vrna_callback_hc_evaluate = Cvoid - @see vrna_plot_layout_free(), vrna_plot_layout_simple(), vrna_plot_layout_naview(), - vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), - vrna_plot_coords(), vrna_file_PS_rnaplot_layout() +""" + vrna_message_constraint_options(option) - @param structure The secondary structure in dot-bracket notation - @param plot_type The layout algorithm to be used - @return The layout data structure for the provided secondary structure + @brief Print a help message for pseudo dot-bracket structure constraint characters to stdout. + (constraint support is specified by option parameter) + + Currently available options are:\\n + #VRNA_CONSTRAINT_DB_PIPE (paired with another base)\\n + #VRNA_CONSTRAINT_DB_DOT (no constraint at all)\\n + #VRNA_CONSTRAINT_DB_X (base must not pair)\\n + #VRNA_CONSTRAINT_DB_ANG_BRACK (paired downstream/upstream)\\n + #VRNA_CONSTRAINT_DB_RND_BRACK (base i pairs base j)\\n + + pass a collection of options as one value like this: + @verbatim vrna_message_constraints(option_1 | option_2 | option_n) @endverbatim + + @ingroup constraints + + @see vrna_message_constraint_options_all(), vrna_constraints_add(), #VRNA_CONSTRAINT_DB, + #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, + #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_INTRAMOL + + @param option Option switch that tells which constraint help will be printed ### Prototype ```c -vrna_plot_layout_t * vrna_plot_layout(const char *structure, unsigned int plot_type); +void vrna_message_constraint_options(unsigned int option); ``` """ -function vrna_plot_layout(structure, plot_type) - ccall((:vrna_plot_layout, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar}, Cuint), structure, plot_type) +function vrna_message_constraint_options(option) + ccall((:vrna_message_constraint_options, libRNA), Cvoid, (Cuint,), option) end """ - vrna_plot_layout_simple(structure) - - @brief Create a layout (coordinates, etc.) for a simple secondary structure plot - - This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. + vrna_message_constraint_options_all() - @note If only X-Y coordinates of the corresponding structure layout are required, consider - using vrna_plot_coords_simple() instead! + @brief Print structure constraint characters to stdout + (full constraint support) - @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), - vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), - vrna_plot_coords_simple(), vrna_file_PS_rnaplot_layout() + @ingroup constraints - @param structure The secondary structure in dot-bracket notation - @return The layout data structure for the provided secondary structure + @see vrna_message_constraint_options(), vrna_constraints_add(), #VRNA_CONSTRAINT_DB, + #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, #VRNA_CONSTRAINT_DB_ANG_BRACK, + #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_INTRAMOL ### Prototype ```c -vrna_plot_layout_t * vrna_plot_layout_simple(const char *structure); +void vrna_message_constraint_options_all(void); ``` """ -function vrna_plot_layout_simple(structure) - ccall((:vrna_plot_layout_simple, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) +function vrna_message_constraint_options_all() + ccall((:vrna_message_constraint_options_all, libRNA), Cvoid, ()) end """ - vrna_plot_layout_circular(structure) + vrna_hc_init(fc) - @brief Create a layout (coordinates, etc.) for a circular secondary structure plot + @brief Initialize/Reset hard constraints to default values - This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. + This function resets the hard constraints to their default values, i.e. + all positions may be unpaired in all contexts, and base pairs are + allowed in all contexts, if they resemble canonical pairs. + Previously set hard constraints will be removed before initialization. - @note If only X-Y coordinates of the corresponding structure layout are required, consider - using vrna_plot_coords_circular() instead! + @ingroup hard_constraints - @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), - vrna_plot_layout_simple(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), - vrna_plot_coords_circular(), vrna_file_PS_rnaplot_layout() + @see vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_add_up() - @param structure The secondary structure in dot-bracket notation - @return The layout data structure for the provided secondary structure + @param fc The fold compound ### Prototype ```c -vrna_plot_layout_t * vrna_plot_layout_circular(const char *structure); +void vrna_hc_init(vrna_fold_compound_t *fc); ``` """ -function vrna_plot_layout_circular(structure) - ccall((:vrna_plot_layout_circular, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) +function vrna_hc_init(fc) + ccall((:vrna_hc_init, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_plot_layout_turtle(structure) - - @brief Create a layout (coordinates, etc.) for a secondary structure plot using the Turtle Algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - - This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_TURTLE. - - @note If only X-Y coordinates of the corresponding structure layout are required, consider - using vrna_plot_coords_turtle() instead! + vrna_hc_init_window(fc) - @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), - vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_puzzler(), - vrna_plot_coords_turtle(), vrna_file_PS_rnaplot_layout() - @param structure The secondary structure in dot-bracket notation - @return The layout data structure for the provided secondary structure ### Prototype ```c -vrna_plot_layout_t * vrna_plot_layout_turtle(const char *structure); +void vrna_hc_init_window(vrna_fold_compound_t *fc); ``` """ -function vrna_plot_layout_turtle(structure) - ccall((:vrna_plot_layout_turtle, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar},), structure) +function vrna_hc_init_window(fc) + ccall((:vrna_hc_init_window, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_plot_layout_puzzler(structure, options) - - @brief Create a layout (coordinates, etc.) for a secondary structure plot using the RNApuzzler Algorithm @rstinline :cite:p:`wiegreffe:2018` @endrst - - This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_PUZZLER. - - @note If only X-Y coordinates of the corresponding structure layout are required, consider - using vrna_plot_coords_puzzler() instead! + vrna_hc_prepare(fc, options) - @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), - vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), - vrna_plot_coords_puzzler(), vrna_file_PS_rnaplot_layout() - @param structure The secondary structure in dot-bracket notation - @return The layout data structure for the provided secondary structure ### Prototype ```c -vrna_plot_layout_t * vrna_plot_layout_puzzler(const char *structure, vrna_plot_options_puzzler_t *options); +int vrna_hc_prepare(vrna_fold_compound_t *fc, unsigned int options); ``` """ -function vrna_plot_layout_puzzler(structure, options) - ccall((:vrna_plot_layout_puzzler, libRNA), Ptr{vrna_plot_layout_t}, (Ptr{Cchar}, Ptr{vrna_plot_options_puzzler_t}), structure, options) +function vrna_hc_prepare(fc, options) + ccall((:vrna_hc_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) end """ - vrna_plot_layout_free(layout) - - @brief Free memory occupied by a figure layout data structure + vrna_hc_update(fc, i, options) - @see #vrna_plot_layout_t, vrna_plot_layout(), vrna_plot_layout_simple(), - vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), - vrna_plot_layout_puzzler(), vrna_file_PS_rnaplot_layout() - @param layout The layout data structure to free ### Prototype ```c -void vrna_plot_layout_free(vrna_plot_layout_t *layout); +void vrna_hc_update(vrna_fold_compound_t *fc, unsigned int i, unsigned int options); ``` """ -function vrna_plot_layout_free(layout) - ccall((:vrna_plot_layout_free, libRNA), Cvoid, (Ptr{vrna_plot_layout_t},), layout) +function vrna_hc_update(fc, i, options) + ccall((:vrna_hc_update, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, i, options) end """ - vrna_plot_coords(structure, x, y, plot_type) - - @brief Compute nucleotide coordinates for secondary structure plot - - This function takes a secondary structure and computes X-Y coordinates - for each nucleotide that then can be used to create a structure plot. - The parameter @p plot_type is used to select the underlying layout algorithm. - Currently, the following selections are provided: - - #VRNA_PLOT_TYPE_SIMPLE - - #VRNA_PLOT_TYPE_NAVIEW - - #VRNA_PLOT_TYPE_CIRCULAR - - #VRNA_PLOT_TYPE_TURTLE - - #VRNA_PLOT_TYPE_PUZZLER + vrna_hc_add_up(fc, i, option) - Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW + @brief Make a certain nucleotide unpaired - Here is a simple example how to use this function, assuming variable @p structure contains - a valid dot-bracket string: - @code{.c} - float *x, *y; + @ingroup hard_constraints - if (vrna_plot_coords(structure, &x, &y)) { - printf("all fine"); - } else { - printf("some failure occured!"); - } + @see vrna_hc_add_bp(), vrna_hc_add_bp_nonspecific(), vrna_hc_init(), + #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, + #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, + #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - free(x); - free(y); - @endcode + @param fc The #vrna_fold_compound_t the hard constraints are associated with + @param i The position that needs to stay unpaired (1-based) + @param option The options flag indicating how/where to store the hard constraints +### Prototype +```c +void vrna_hc_add_up(vrna_fold_compound_t *fc, int i, unsigned char option); +``` +""" +function vrna_hc_add_up(fc, i, option) + ccall((:vrna_hc_add_up, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, Cuchar), fc, i, option) +end - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! +""" + vrna_hc_add_up_strand(fc, i, strand, option) - @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_naview() - vrna_plot_coords_circular(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() - @param structure The secondary structure in dot-bracket notation - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param plot_type The layout algorithm to be used - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords(const char *structure, float **x, float **y, int plot_type); +int vrna_hc_add_up_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int strand, unsigned char option); ``` """ -function vrna_plot_coords(structure, x, y, plot_type) - ccall((:vrna_plot_coords, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Cint), structure, x, y, plot_type) +function vrna_hc_add_up_strand(fc, i, strand, option) + ccall((:vrna_hc_add_up_strand, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuchar), fc, i, strand, option) end """ - vrna_plot_coords_pt(pt, x, y, plot_type) - - @brief Compute nucleotide coordinates for secondary structure plot - - Same as vrna_plot_coords() but takes a pair table with the structure - information as input. + vrna_hc_add_up_batch(fc, constraints) - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! + @brief Apply a list of hard constraints for single nucleotides - @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_naview_pt() - vrna_plot_coords_circular_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() + @ingroup hard_constraints - @param pt The pair table that holds the secondary structure - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @param plot_type The layout algorithm to be used - @return The length of the structure on success, 0 otherwise + @param fc The #vrna_fold_compound_t the hard constraints are associated with + @param constraints The list off constraints to apply, last entry must have position + attribute set to 0 ### Prototype ```c -int vrna_plot_coords_pt(const short *pt, float **x, float **y, int plot_type); +int vrna_hc_add_up_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints); ``` """ -function vrna_plot_coords_pt(pt, x, y, plot_type) - ccall((:vrna_plot_coords_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}, Cint), pt, x, y, plot_type) +function vrna_hc_add_up_batch(fc, constraints) + ccall((:vrna_hc_add_up_batch, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_hc_up_t}), fc, constraints) end """ - vrna_plot_coords_simple(structure, x, y) + vrna_hc_add_up_strand_batch(fc, constraints) - @brief Compute nucleotide coordinates for secondary structure plot the Simple way - This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. +### Prototype +```c +int vrna_hc_add_up_strand_batch(vrna_fold_compound_t *fc, vrna_hc_up_t *constraints); +``` +""" +function vrna_hc_add_up_strand_batch(fc, constraints) + ccall((:vrna_hc_add_up_strand_batch, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_hc_up_t}), fc, constraints) +end - Here is a simple example how to use this function, assuming variable @p structure contains - a valid dot-bracket string: - @code{.c} - float *x, *y; +""" + vrna_hc_add_bp(fc, i, j, option) - if (vrna_plot_coords_simple(structure, &x, &y)) { - printf("all fine"); - } else { - printf("some failure occured!"); - } + @brief Favorize/Enforce a certain base pair (i,j) - free(x); - free(y); - @endcode + @ingroup hard_constraints - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! + @see vrna_hc_add_bp_nonspecific(), vrna_hc_add_up(), vrna_hc_init(), + #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, + #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, + #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, + #VRNA_CONSTRAINT_CONTEXT_ENFORCE, #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS + + @param fc The #vrna_fold_compound_t the hard constraints are associated with + @param i The 5' located nucleotide position of the base pair (1-based) + @param j The 3' located nucleotide position of the base pair (1-based) + @param option The options flag indicating how/where to store the hard constraints +### Prototype +```c +int vrna_hc_add_bp(vrna_fold_compound_t *fc, int i, int j, unsigned char option); +``` +""" +function vrna_hc_add_bp(fc, i, j, option) + ccall((:vrna_hc_add_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cint, Cuchar), fc, i, j, option) +end + +""" + vrna_hc_add_bp_strand(fc, i, strand_i, j, strand_j, option) - @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_circular(), - vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() - @param structure The secondary structure in dot-bracket notation - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise ### Prototype ```c -int vrna_plot_coords_simple(const char *structure, float **x, float **y); +int vrna_hc_add_bp_strand(vrna_fold_compound_t *fc, unsigned int i, unsigned int strand_i, unsigned int j, unsigned int strand_j, unsigned char option); ``` """ -function vrna_plot_coords_simple(structure, x, y) - ccall((:vrna_plot_coords_simple, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), structure, x, y) +function vrna_hc_add_bp_strand(fc, i, strand_i, j, strand_j, option) + ccall((:vrna_hc_add_bp_strand, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint, Cuint, Cuint, Cuchar), fc, i, strand_i, j, strand_j, option) end """ - vrna_plot_coords_simple_pt(pt, x, y) - - @brief Compute nucleotide coordinates for secondary structure plot the Simple way + vrna_hc_add_bp_nonspecific(fc, i, d, option) - Same as vrna_plot_coords_simple() but takes a pair table with the structure - information as input. + @brief Enforce a nucleotide to be paired (upstream/downstream) - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! + @ingroup hard_constraints - @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_circular_pt(), - vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() + @see vrna_hc_add_bp(), vrna_hc_add_up(), vrna_hc_init(), + #VRNA_CONSTRAINT_CONTEXT_EXT_LOOP, #VRNA_CONSTRAINT_CONTEXT_HP_LOOP, + #VRNA_CONSTRAINT_CONTEXT_INT_LOOP, #VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC, + #VRNA_CONSTRAINT_CONTEXT_MB_LOOP, #VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC, + #VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS - @param pt The pair table that holds the secondary structure - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise + @param fc The #vrna_fold_compound_t the hard constraints are associated with + @param i The position that needs to stay unpaired (1-based) + @param d The direction of base pairing (@f\$ d < 0 @f\$: pairs upstream, + @f\$ d > 0 @f\$: pairs downstream, @f\$ d == 0 @f\$: no direction) + @param option The options flag indicating in which loop type context the pairs may appear ### Prototype ```c -int vrna_plot_coords_simple_pt(const short *pt, float **x, float **y); +void vrna_hc_add_bp_nonspecific(vrna_fold_compound_t *fc, int i, int d, unsigned char option); ``` """ -function vrna_plot_coords_simple_pt(pt, x, y) - ccall((:vrna_plot_coords_simple_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), pt, x, y) +function vrna_hc_add_bp_nonspecific(fc, i, d, option) + ccall((:vrna_hc_add_bp_nonspecific, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, Cint, Cuchar), fc, i, d, option) end """ - vrna_plot_coords_circular(structure, x, y) - - @brief Compute coordinates of nucleotides mapped in equal distancies onto a unit circle. - - This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. + vrna_hc_free(hc) - In order to draw nice arcs using quadratic bezier curves that connect base pairs one may calculate - a second tangential point @f\$P^t@f\$ in addition to the actual R2 coordinates. - the simplest way to do so may be to compute a radius scaling factor @f\$rs@f\$ in the interval @f\$[0,1]@f\$ that - weights the proportion of base pair span to the actual length of the sequence. This scaling factor - can then be used to calculate the coordinates for @f\$P^t@f\$, i.e. + @brief Free the memory allocated by a #vrna_hc_t data structure - @f[ P^{t}_x[i] = X[i] * rs @f] + Use this function to free all memory that was allocated for a data structure + of type #vrna_hc_t . - and + @see get_hard_constraints(), #vrna_hc_t - @f[ P^{t}_y[i] = Y[i] * rs @f]. + @ingroup hard_constraints - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! +### Prototype +```c +void vrna_hc_free(vrna_hc_t *hc); +``` +""" +function vrna_hc_free(hc) + ccall((:vrna_hc_free, libRNA), Cvoid, (Ptr{vrna_hc_t},), hc) +end - @see vrna_plot_coords(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple(), - vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() +""" + vrna_hc_add_f(fc, f) - @param structure The secondary structure in dot-bracket notation - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise + @brief Add a function pointer pointer for the generic hard constraint + feature ### Prototype ```c -int vrna_plot_coords_circular(const char *structure, float **x, float **y); +void vrna_hc_add_f(vrna_fold_compound_t *fc, vrna_hc_eval_f f); ``` """ -function vrna_plot_coords_circular(structure, x, y) - ccall((:vrna_plot_coords_circular, libRNA), Cint, (Ptr{Cchar}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), structure, x, y) +function vrna_hc_add_f(fc, f) + ccall((:vrna_hc_add_f, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, vrna_hc_eval_f), fc, f) end """ - vrna_plot_coords_circular_pt(pt, x, y) - - @brief Compute nucleotide coordinates for a Circular Plot + vrna_hc_add_data(fc, data, f) - Same as vrna_plot_coords_circular() but takes a pair table with the structure - information as input. + @brief Add an auxiliary data structure for the generic hard constraints callback function - @note On success, this function allocates memory for X and Y coordinates and assigns - the pointers at addressess @p x and @p y to the corresponding memory locations. It's - the users responsibility to cleanup this memory after usage! + @ingroup generic_hc - @see vrna_plot_coords_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple_pt(), - vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() + @see vrna_hc_add_f() - @param pt The pair table that holds the secondary structure - @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) - @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) - @return The length of the structure on success, 0 otherwise + @param fc The fold compound the generic hard constraint function should be bound to + @param data A pointer to the data structure that holds required data for function 'f' + @param f A pointer to a function that free's the memory occupied by @p data (Maybe @p NULL) ### Prototype ```c -int vrna_plot_coords_circular_pt(const short *pt, float **x, float **y); +void vrna_hc_add_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f f); ``` """ -function vrna_plot_coords_circular_pt(pt, x, y) - ccall((:vrna_plot_coords_circular_pt, libRNA), Cint, (Ptr{Cshort}, Ptr{Ptr{Cfloat}}, Ptr{Ptr{Cfloat}}), pt, x, y) +function vrna_hc_add_data(fc, data, f) + ccall((:vrna_hc_add_data, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, f) end """ - COORDINATE + vrna_hc_add_from_db(fc, constraint, options) - @brief this is a workarround for the SWIG Perl Wrapper RNA plot function - that returns an array of type COORDINATE -""" -struct COORDINATE - X::Cfloat - Y::Cfloat -end + @brief Add hard constraints from pseudo dot-bracket notation -""" - simple_xy_coordinates(pair_table, X, Y) + This function allows one to apply hard constraints from a pseudo dot-bracket + notation. The @p options parameter controls, which characters are recognized + by the parser. Use the #VRNA_CONSTRAINT_DB_DEFAULT convenience macro, if you + want to allow all known characters + + @ingroup hard_constraints + @see #VRNA_CONSTRAINT_DB_PIPE, #VRNA_CONSTRAINT_DB_DOT, #VRNA_CONSTRAINT_DB_X, + #VRNA_CONSTRAINT_DB_ANG_BRACK, #VRNA_CONSTRAINT_DB_RND_BRACK, #VRNA_CONSTRAINT_DB_INTRAMOL, + #VRNA_CONSTRAINT_DB_INTERMOL, #VRNA_CONSTRAINT_DB_GQUAD + @param fc The fold compound + @param constraint A pseudo dot-bracket notation of the hard constraint. + @param options The option flags ### Prototype ```c -; +int vrna_hc_add_from_db(vrna_fold_compound_t *fc, const char *constraint, unsigned int options); ``` """ -function simple_xy_coordinates(pair_table, X, Y) - ccall((:simple_xy_coordinates, libRNA), Cint, (Ptr{Cshort}, Ptr{Cfloat}, Ptr{Cfloat}), pair_table, X, Y) +function vrna_hc_add_from_db(fc, constraint, options) + ccall((:vrna_hc_add_from_db, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Cuint), fc, constraint, options) end """ - simple_circplot_coordinates(pair_table, x, y) + print_tty_constraint(option) ### Prototype @@ -11345,749 +11639,1016 @@ end ; ``` """ -function simple_circplot_coordinates(pair_table, x, y) - ccall((:simple_circplot_coordinates, libRNA), Cint, (Ptr{Cshort}, Ptr{Cfloat}, Ptr{Cfloat}), pair_table, x, y) +function print_tty_constraint(option) + ccall((:print_tty_constraint, libRNA), Cvoid, (Cuint,), option) end """ - vrna_subopt_sol_s + print_tty_constraint_full() - @brief Solution element from subopt.c -""" -struct vrna_subopt_sol_s - energy::Cfloat - structure::Ptr{Cchar} -end +### Prototype +```c +; +``` """ - @brief Typename for the subopt solution list repesenting data structure #vrna_subopt_sol_s -""" -const vrna_subopt_solution_t = vrna_subopt_sol_s +function print_tty_constraint_full() + ccall((:print_tty_constraint_full, libRNA), Cvoid, ()) +end -# typedef void ( * vrna_subopt_result_f ) ( const char * stucture , float energy , void * data ) """ - @brief Callback for vrna_subopt_cb() - @ingroup subopt_wuchty - -@callback -@parblock -This function will be called for each suboptimal secondary structure that is successfully backtraced. -@endparblock + constrain_ptypes(constraint, length, ptype, BP, min_loop_size, idx_type) -@see vrna_subopt_cb() -@param structure The suboptimal secondary structure in dot-bracket notation -@param energy The free energy of the secondary structure in kcal/mol -@param data Some arbitrary, auxiliary data address as passed to vrna_subopt_cb() +### Prototype +```c +; +``` """ -const vrna_subopt_result_f = Ptr{Cvoid} +function constrain_ptypes(constraint, length, ptype, BP, min_loop_size, idx_type) + ccall((:constrain_ptypes, libRNA), Cvoid, (Ptr{Cchar}, Cuint, Ptr{Cchar}, Ptr{Cint}, Cint, Cuint), constraint, length, ptype, BP, min_loop_size, idx_type) +end -# DEPRECATED -const vrna_subopt_callback = Cvoid +struct vrna_sc_motif_s + i::Cint + j::Cint + k::Cint + l::Cint + number::Cint +end """ - @brief Backward compatibility typedef for #vrna_subopt_sol_s - @deprecated Use #vrna_subopt_solution_t instead! +@brief Type definition for soft constraint motif """ -const SOLUTION = vrna_subopt_sol_s +const vrna_sc_motif_t = vrna_sc_motif_s """ - vrna_subopt(fc, delta, sorted, fp) - - @brief Returns list of subopt structures or writes to fp + vrna_sc_add_hi_motif(fc, seq, structure, energy, options) - This function produces all suboptimal secondary structures within - 'delta' * 0.01 kcal/mol of the optimum, see @rstinline :cite:t:`wuchty:1999` @endrst. The results - are either directly written to a 'fp' (if 'fp' is not NULL), or - (fp==NULL) returned in a #vrna_subopt_solution_t * list terminated - by an entry were the 'structure' member is NULL. + @brief Add soft constraints for hairpin or interior loop binding motif - @ingroup subopt_wuchty + Here is an example that adds a theophylline binding motif. Free energy + contribution is derived from @f\$k_d = 0.1 \\mu M@f\$, taken from + Jenison et al. 1994. At @f\$1M@f\$ concentration the corresponding binding + free energy amounts to @f\$-9.93~kcal/mol@f\$. - @note This function requires all multibranch loop DP matrices for unique - multibranch loop backtracing. Therefore, the supplied #vrna_fold_compound_t - @p fc (argument 1) must be initialized with #vrna_md_t.uniq_ML = 1, for - instance like this: - @code -vrna_md_t md; -vrna_md_set_default(&md); -md.uniq_ML = 1; + @image xml theo_aptamer.svg -vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT); - @endcode + @code{.c} +vrna_sc_add_hi_motif(fc, + "GAUACCAG&CCCUUGGCAGC", + "(...((((&)...)))...)", + -9.93, VRNA_OPTION_DEFAULT); +@endcode - @see vrna_subopt_cb(), vrna_subopt_zuker() + @param fc The #vrna_fold_compound_t the motif is applied to + @param seq The sequence motif (may be interspaced by '&' character + @param structure The structure motif (may be interspaced by '&' character + @param energy The free energy of the motif (e.g. binding free energy) + @param options Options + @return non-zero value if application of the motif using soft constraints was successful - @param fc - @param delta - @param sorted Sort results by energy in ascending order - @param fp - @return ### Prototype ```c -vrna_subopt_solution_t * vrna_subopt(vrna_fold_compound_t *fc, int delta, int sorted, FILE *fp); +int vrna_sc_add_hi_motif(vrna_fold_compound_t *fc, const char *seq, const char *structure, FLT_OR_DBL energy, unsigned int options); ``` """ -function vrna_subopt(fc, delta, sorted, fp) - ccall((:vrna_subopt, libRNA), Ptr{vrna_subopt_solution_t}, (Ptr{vrna_fold_compound_t}, Cint, Cint, Ptr{Libc.FILE}), fc, delta, sorted, fp) +function vrna_sc_add_hi_motif(fc, seq, structure, energy, options) + ccall((:vrna_sc_add_hi_motif, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Cchar}, FLT_OR_DBL, Cuint), fc, seq, structure, energy, options) end -""" - vrna_subopt_cb(fc, delta, cb, data) - - @brief Generate suboptimal structures within an energy band arround the MFE - - This is the most generic implementation of the suboptimal structure generator - according to @rstinline :cite:t:`wuchty:1999` @endrst. Identical to vrna_subopt(), it computes all - secondary structures within an energy band @p delta arround the MFE. However, - this function does not print the resulting structures and their corresponding - free energies to a file pointer, or returns them as a list. Instead, it calls - a user-provided callback function which it passes the structure in dot-bracket - format, the corresponding free energy in kcal/mol, and a user-provided data - structure each time a structure was backtracked successfully. This function - indicates the final output, i.e. the end of the backtracking procedure by - passing NULL instead of an actual dot-bracket string to the callback. - - @ingroup subopt_wuchty - - @note This function requires all multibranch loop DP matrices for unique - multibranch loop backtracing. Therefore, the supplied #vrna_fold_compound_t - @p fc (argument 1) must be initialized with #vrna_md_t.uniq_ML = 1, for - instance like this: - @code -vrna_md_t md; -vrna_md_set_default(&md); -md.uniq_ML = 1; +""" + vrna_sc_ligand_detect_motifs(fc, structure) -vrna_fold_compound_t *fc=vrna_fold_compound("GGGGGGAAAAAACCCCCC", &md, VRNA_OPTION_DEFAULT); - @endcode - @see vrna_subopt_result_f, vrna_subopt(), vrna_subopt_zuker() +### Prototype +```c +vrna_sc_motif_t * vrna_sc_ligand_detect_motifs(vrna_fold_compound_t *fc, const char *structure); +``` +""" +function vrna_sc_ligand_detect_motifs(fc, structure) + ccall((:vrna_sc_ligand_detect_motifs, libRNA), Ptr{vrna_sc_motif_t}, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}), fc, structure) +end + +""" + vrna_sc_ligand_get_all_motifs(fc) + - @param fc fold compount with the sequence data - @param delta Energy band arround the MFE in 10cal/mol, i.e. deka-calories - @param cb Pointer to a callback function that handles the backtracked structure and its free energy in kcal/mol - @param data Pointer to some data structure that is passed along to the callback ### Prototype ```c -void vrna_subopt_cb(vrna_fold_compound_t *fc, int delta, vrna_subopt_result_f cb, void *data); +vrna_sc_motif_t * vrna_sc_ligand_get_all_motifs(vrna_fold_compound_t *fc); ``` """ -function vrna_subopt_cb(fc, delta, cb, data) - ccall((:vrna_subopt_cb, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Cint, vrna_subopt_result_f, Ptr{Cvoid}), fc, delta, cb, data) +function vrna_sc_ligand_get_all_motifs(fc) + ccall((:vrna_sc_ligand_get_all_motifs, libRNA), Ptr{vrna_sc_motif_t}, (Ptr{vrna_fold_compound_t},), fc) end """ - subopt(seq, structure, delta, fp) + vrna_constraints_add_SHAPE(fc, shape_file, shape_method, shape_conversion, verbose, constraint_type) + + @ingroup SHAPE_reactivities +### Prototype +```c +void vrna_constraints_add_SHAPE(vrna_fold_compound_t *fc, const char *shape_file, const char *shape_method, const char *shape_conversion, int verbose, unsigned int constraint_type); +``` +""" +function vrna_constraints_add_SHAPE(fc, shape_file, shape_method, shape_conversion, verbose, constraint_type) + ccall((:vrna_constraints_add_SHAPE, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Cchar}, Ptr{Cchar}, Cint, Cuint), fc, shape_file, shape_method, shape_conversion, verbose, constraint_type) +end +""" + vrna_constraints_add_SHAPE_ali(fc, shape_method, shape_files, shape_file_association, verbose, constraint_type) + @ingroup SHAPE_reactivities ### Prototype ```c -; +void vrna_constraints_add_SHAPE_ali(vrna_fold_compound_t *fc, const char *shape_method, const char **shape_files, const int *shape_file_association, int verbose, unsigned int constraint_type); ``` """ -function subopt(seq, structure, delta, fp) - ccall((:subopt, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), seq, structure, delta, fp) +function vrna_constraints_add_SHAPE_ali(fc, shape_method, shape_files, shape_file_association, verbose, constraint_type) + ccall((:vrna_constraints_add_SHAPE_ali, libRNA), Cvoid, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Ptr{Cchar}}, Ptr{Cint}, Cint, Cuint), fc, shape_method, shape_files, shape_file_association, verbose, constraint_type) end """ - subopt_par(seq, structure, parameters, delta, is_constrained, is_circular, fp) + vrna_sc_add_SHAPE_deigan(fc, reactivities, m, b, options) + + @brief Add SHAPE reactivity data as soft constraints (Deigan et al. method) + This approach of SHAPE directed RNA folding uses the simple linear ansatz + @f[ \\Delta G_{\\text{SHAPE}}(i) = m \\ln(\\text{SHAPE reactivity}(i)+1)+ b @f] + + to convert SHAPE reactivity values to pseudo energies whenever a + nucleotide @f\$ i @f\$ contributes to a stacked pair. A positive slope @f\$ m @f\$ + penalizes high reactivities in paired regions, while a negative intercept @f\$ b @f\$ + results in a confirmatory ``bonus'' free energy for correctly predicted base pairs. + Since the energy evaluation of a base pair stack involves two pairs, the pseudo + energies are added for all four contributing nucleotides. Consequently, the + energy term is applied twice for pairs inside a helix and only once for pairs + adjacent to other structures. For all other loop types the energy model remains + unchanged even when the experimental data highly disagrees with a certain motif. + + @note For further details, we refer to @rstinline :cite:t:`deigan:2009` @endrst. + + @see vrna_sc_remove(), vrna_sc_add_SHAPE_zarringhalam(), vrna_sc_minimize_pertubation() + + @ingroup SHAPE_reactivities + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param reactivities A vector of normalized SHAPE reactivities + @param m The slope of the conversion function + @param b The intercept of the conversion function + @param options The options flag indicating how/where to store the soft constraints + @return 1 on successful extraction of the method, 0 on errors ### Prototype ```c -; +int vrna_sc_add_SHAPE_deigan(vrna_fold_compound_t *fc, const double *reactivities, double m, double b, unsigned int options); ``` """ -function subopt_par(seq, structure, parameters, delta, is_constrained, is_circular, fp) - ccall((:subopt_par, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Ptr{vrna_param_t}, Cint, Cint, Cint, Ptr{Libc.FILE}), seq, structure, parameters, delta, is_constrained, is_circular, fp) +function vrna_sc_add_SHAPE_deigan(fc, reactivities, m, b, options) + ccall((:vrna_sc_add_SHAPE_deigan, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cdouble}, Cdouble, Cdouble, Cuint), fc, reactivities, m, b, options) end """ - subopt_circ(seq, sequence, delta, fp) + vrna_sc_add_SHAPE_deigan_ali(fc, shape_files, shape_file_association, m, b, options) + @brief Add SHAPE reactivity data from files as soft constraints for consensus structure prediction (Deigan et al. method) + @ingroup SHAPE_reactivities + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param shape_files A set of filenames that contain normalized SHAPE reactivity data + @param shape_file_association An array of integers that associate the files with sequences in the alignment + @param m The slope of the conversion function + @param b The intercept of the conversion function + @param options The options flag indicating how/where to store the soft constraints + @return 1 on successful extraction of the method, 0 on errors ### Prototype ```c -; +int vrna_sc_add_SHAPE_deigan_ali(vrna_fold_compound_t *fc, const char **shape_files, const int *shape_file_association, double m, double b, unsigned int options); ``` """ -function subopt_circ(seq, sequence, delta, fp) - ccall((:subopt_circ, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{Cchar}, Cint, Ptr{Libc.FILE}), seq, sequence, delta, fp) +function vrna_sc_add_SHAPE_deigan_ali(fc, shape_files, shape_file_association, m, b, options) + ccall((:vrna_sc_add_SHAPE_deigan_ali, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{Cchar}}, Ptr{Cint}, Cdouble, Cdouble, Cuint), fc, shape_files, shape_file_association, m, b, options) end """ - zukersubopt(string) + vrna_sc_add_SHAPE_zarringhalam(fc, reactivities, b, default_value, shape_conversion, options) + + @brief Add SHAPE reactivity data as soft constraints (Zarringhalam et al. method) + + This method first converts the observed SHAPE reactivity of nucleotide @f\$ i @f\$ into a + probability @f\$ q_i @f\$ that position @f\$ i @f\$ is unpaired by means of a non-linear map. + Then pseudo-energies of the form + + @f[ \\Delta G_{\\text{SHAPE}}(x,i) = \\beta\\ |x_i - q_i| @f] + + are computed, where @f\$ x_i=0 @f\$ if position @f\$ i @f\$ is unpaired and @f\$ x_i=1 @f\$ + if @f\$ i @f\$ is paired in a given secondary structure. The parameter @f\$ \\beta @f\$ serves as + scaling factor. The magnitude of discrepancy between prediction and experimental observation + is represented by @f\$ |x_i - q_i| @f\$. + @note For further details, we refer to @rstinline :cite:t:`zarringhalam:2012` @endrst + @see vrna_sc_remove(), vrna_sc_add_SHAPE_deigan(), vrna_sc_minimize_pertubation() + + @ingroup SHAPE_reactivities + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param reactivities A vector of normalized SHAPE reactivities + @param b The scaling factor @f\$ \\beta @f\$ of the conversion function + @param default_value The default value for a nucleotide where reactivity data is missing for + @param shape_conversion A flag that specifies how to convert reactivities to probabilities + @param options The options flag indicating how/where to store the soft constraints + @return 1 on successful extraction of the method, 0 on errors ### Prototype ```c -; +int vrna_sc_add_SHAPE_zarringhalam(vrna_fold_compound_t *fc, const double *reactivities, double b, double default_value, const char *shape_conversion, unsigned int options); ``` """ -function zukersubopt(string) - ccall((:zukersubopt, libRNA), Ptr{SOLUTION}, (Ptr{Cchar},), string) +function vrna_sc_add_SHAPE_zarringhalam(fc, reactivities, b, default_value, shape_conversion, options) + ccall((:vrna_sc_add_SHAPE_zarringhalam, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cdouble}, Cdouble, Cdouble, Ptr{Cchar}, Cuint), fc, reactivities, b, default_value, shape_conversion, options) end """ - zukersubopt_par(string, parameters) + vrna_sc_SHAPE_parse_method(method_string, method, param_1, param_2) + + @brief Parse a character string and extract the encoded SHAPE reactivity conversion + method and possibly the parameters for conversion into pseudo free energies + @ingroup soft_cosntraints + @param method_string The string that contains the encoded SHAPE reactivity conversion method + @param method A pointer to the memory location where the method character will be stored + @param param_1 A pointer to the memory location where the first parameter of the corresponding method will be stored + @param param_2 A pointer to the memory location where the second parameter of the corresponding method will be stored + @return 1 on successful extraction of the method, 0 on errors ### Prototype ```c -; +int vrna_sc_SHAPE_parse_method(const char *method_string, char *method, float *param_1, float *param_2); ``` """ -function zukersubopt_par(string, parameters) - ccall((:zukersubopt_par, libRNA), Ptr{SOLUTION}, (Ptr{Cchar}, Ptr{vrna_param_t}), string, parameters) +function vrna_sc_SHAPE_parse_method(method_string, method, param_1, param_2) + ccall((:vrna_sc_SHAPE_parse_method, libRNA), Cint, (Ptr{Cchar}, Ptr{Cchar}, Ptr{Cfloat}, Ptr{Cfloat}), method_string, method, param_1, param_2) end """ - vrna_subopt_zuker(fc) + vrna_sc_SHAPE_to_pr(shape_conversion, values, length, default_value) - @brief Compute Zuker type suboptimal structures + @brief Convert SHAPE reactivity values to probabilities for being unpaired - Compute Suboptimal structures according to @rstinline :cite:t:`zuker:1989` @endrst , i.e. for every - possible base pair the minimum energy structure containing the resp. base pair. - Returns a list of these structures and their energies. + This function parses the informations from a given file and stores the result + in the preallocated string sequence and the #FLT_OR_DBL array values. - @ingroup subopt_zuker + @ingroup SHAPE_reactivities - @see vrna_subopt(), zukersubopt(), zukersubopt_par() + @see vrna_file_SHAPE_read() - @param fc fold compound - @return List of zuker suboptimal structures + @param shape_conversion String definining the method used for the conversion process + @param values Pointer to an array of SHAPE reactivities + @param length Length of the array of SHAPE reactivities + @param default_value Result used for position with invalid/missing reactivity values ### Prototype ```c -vrna_subopt_solution_t * vrna_subopt_zuker(vrna_fold_compound_t *fc); +int vrna_sc_SHAPE_to_pr(const char *shape_conversion, double *values, int length, double default_value); ``` """ -function vrna_subopt_zuker(fc) - ccall((:vrna_subopt_zuker, libRNA), Ptr{vrna_subopt_solution_t}, (Ptr{vrna_fold_compound_t},), fc) +function vrna_sc_SHAPE_to_pr(shape_conversion, values, length, default_value) + ccall((:vrna_sc_SHAPE_to_pr, libRNA), Cint, (Ptr{Cchar}, Ptr{Cdouble}, Cint, Cdouble), shape_conversion, values, length, default_value) end +# DEPRECATED +const vrna_callback_sc_energy = Cvoid + +# typedef int ( * vrna_sc_direct_f ) ( vrna_fold_compound_t * fc , int i , int j , int k , int l , void * data ) +const vrna_sc_direct_f = Ptr{Cvoid} + +# DEPRECATED +const vrna_callback_sc_exp_energy = Cvoid + +# typedef FLT_OR_DBL ( * vrna_sc_exp_direct_f ) ( vrna_fold_compound_t * fc , int i , int j , int k , int l , void * data ) +const vrna_sc_exp_direct_f = Ptr{Cvoid} + +# DEPRECATED +const vrna_callback_sc_backtrack = Cvoid + """ - Postorder_list + vrna_sc_init(fc) - @brief Postorder data structure + @brief Initialize an empty soft constraints data structure within a #vrna_fold_compound_t + + 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. + + \\note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE + + @ingroup soft_constraints + + @see 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() + + @param fc The #vrna_fold_compound_t where an empty soft constraint feature is to be added to +### Prototype +```c +void vrna_sc_init(vrna_fold_compound_t *fc); +``` """ -struct Postorder_list - type::Cint - weight::Cint - father::Cint - sons::Cint - leftmostleaf::Cint +function vrna_sc_init(fc) + ccall((:vrna_sc_init, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - Tree + vrna_sc_prepare(fc, options) - @brief Tree data structure + +### Prototype +```c +int vrna_sc_prepare(vrna_fold_compound_t *fc, unsigned int options); +``` """ -struct Tree - postorder_list::Ptr{Postorder_list} - keyroots::Ptr{Cint} +function vrna_sc_prepare(fc, options) + ccall((:vrna_sc_prepare, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint), fc, options) end """ - swString + vrna_sc_update(fc, i, options) - @brief Some other data structure + +### Prototype +```c +int vrna_sc_update(vrna_fold_compound_t *fc, unsigned int i, unsigned int options); +``` """ -struct swString - type::Cint - sign::Cint - weight::Cfloat +function vrna_sc_update(fc, i, options) + ccall((:vrna_sc_update, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cuint, Cuint), fc, i, options) end """ - make_tree(struc) + vrna_sc_set_bp(fc, constraints, options) - \\brief Constructs a Tree ( essentially the postorder list ) of the - structure 'struc', for use in tree_edit_distance(). + @brief Set soft constraints for paired nucleotides - \\param struc may be any rooted structure representation. - \\return + @note This function replaces any pre-exisitng soft constraints with the ones supplied + in @p constraints. + + @ingroup soft_constraints + + @see vrna_sc_add_bp(), vrna_sc_set_up(), vrna_sc_add_up() + + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param constraints A two-dimensional array of pseudo free energies in @f\$ kcal / mol @f\$ + @param options The options flag indicating how/where to store the soft constraints + @return Non-zero on successful application of the constraint, 0 otherwise. ### Prototype ```c -Tree *make_tree(char *struc); +int vrna_sc_set_bp(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options); ``` """ -function make_tree(struc) - ccall((:make_tree, libRNA), Ptr{Tree}, (Ptr{Cchar},), struc) +function vrna_sc_set_bp(fc, constraints, options) + ccall((:vrna_sc_set_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{FLT_OR_DBL}}, Cuint), fc, constraints, options) end """ - tree_edit_distance(T1, T2) + vrna_sc_add_bp(fc, i, j, energy, options) - \\brief Calculates the edit distance of the two trees. + @brief Add soft constraints for paired nucleotides - \\param T1 - \\param T2 - \\return + @ingroup soft_constraints + + @see vrna_sc_set_bp(), vrna_sc_set_up(), vrna_sc_add_up() + + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param i The 5' position of the base pair the soft constraint is added for + @param j The 3' position of the base pair the soft constraint is added for + @param energy The free energy (soft-constraint) in @f\$ kcal / mol @f\$ + @param options The options flag indicating how/where to store the soft constraints + @return Non-zero on successful application of the constraint, 0 otherwise. ### Prototype ```c -float tree_edit_distance(Tree *T1, Tree *T2); +int vrna_sc_add_bp(vrna_fold_compound_t *fc, int i, int j, FLT_OR_DBL energy, unsigned int options); ``` """ -function tree_edit_distance(T1, T2) - ccall((:tree_edit_distance, libRNA), Cfloat, (Ptr{Tree}, Ptr{Tree}), T1, T2) +function vrna_sc_add_bp(fc, i, j, energy, options) + ccall((:vrna_sc_add_bp, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Cint, FLT_OR_DBL, Cuint), fc, i, j, energy, options) end """ - print_tree(t) + vrna_sc_set_up(fc, constraints, options) - \\brief Print a tree (mainly for debugging) + @brief Set soft constraints for unpaired nucleotides + + @note This function replaces any pre-exisitng soft constraints with the ones supplied + in @p constraints. + + @ingroup soft_constraints + + @see vrna_sc_add_up(), vrna_sc_set_bp(), vrna_sc_add_bp() + + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param constraints A vector of pseudo free energies in @f\$ kcal / mol @f\$ + @param options The options flag indicating how/where to store the soft constraints + @return Non-zero on successful application of the constraint, 0 otherwise. ### Prototype ```c -void print_tree(Tree *t); +int vrna_sc_set_up(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options); ``` """ -function print_tree(t) - ccall((:print_tree, libRNA), Cvoid, (Ptr{Tree},), t) +function vrna_sc_set_up(fc, constraints, options) + ccall((:vrna_sc_set_up, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{FLT_OR_DBL}, Cuint), fc, constraints, options) end """ - free_tree(t) + vrna_sc_add_up(fc, i, energy, options) - \\brief Free the memory allocated for Tree t. + @brief Add soft constraints for unpaired nucleotides - \\param t + @ingroup soft_constraints + + @see vrna_sc_set_up(), vrna_sc_add_bp(), vrna_sc_set_bp() + + @param fc The #vrna_fold_compound_t the soft constraints are associated with + @param i The nucleotide position the soft constraint is added for + @param energy The free energy (soft-constraint) in @f\$ kcal / mol @f\$ + @param options The options flag indicating how/where to store the soft constraints + @return Non-zero on successful application of the constraint, 0 otherwise. ### Prototype ```c -void free_tree(Tree *t); +int vrna_sc_add_up(vrna_fold_compound_t *fc, int i, FLT_OR_DBL energy, unsigned int options); ``` """ -function free_tree(t) - ccall((:free_tree, libRNA), Cvoid, (Ptr{Tree},), t) +function vrna_sc_add_up(fc, i, energy, options) + ccall((:vrna_sc_add_up, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, FLT_OR_DBL, Cuint), fc, i, energy, options) end """ - vrna_alloc(size) + vrna_sc_set_stack(fc, constraints, options) - @brief Allocate space safely - @param size The size of the memory to be allocated in bytes - @return A pointer to the allocated memory ### Prototype ```c -void * vrna_alloc(unsigned size); +int vrna_sc_set_stack(vrna_fold_compound_t *fc, const FLT_OR_DBL *constraints, unsigned int options); ``` """ -function vrna_alloc(size) - ccall((:vrna_alloc, libRNA), Ptr{Cvoid}, (Cuint,), size) +function vrna_sc_set_stack(fc, constraints, options) + ccall((:vrna_sc_set_stack, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{FLT_OR_DBL}, Cuint), fc, constraints, options) end """ - vrna_realloc(p, size) + vrna_sc_set_stack_comparative(fc, constraints, options) - @brief Reallocate space safely - @param p A pointer to the memory region to be reallocated - @param size The size of the memory to be allocated in bytes - @return A pointer to the newly allocated memory ### Prototype ```c -void * vrna_realloc(void *p, unsigned size); +int vrna_sc_set_stack_comparative(vrna_fold_compound_t *fc, const FLT_OR_DBL **constraints, unsigned int options); ``` """ -function vrna_realloc(p, size) - ccall((:vrna_realloc, libRNA), Ptr{Cvoid}, (Ptr{Cvoid}, Cuint), p, size) +function vrna_sc_set_stack_comparative(fc, constraints, options) + ccall((:vrna_sc_set_stack_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{FLT_OR_DBL}}, Cuint), fc, constraints, options) end """ - vrna_init_rand() + vrna_sc_add_stack(fc, i, energy, options) - @brief Initialize seed for random number generator - @see vrna_init_rand_seed(), vrna_urn() ### Prototype ```c -void vrna_init_rand(void); +int vrna_sc_add_stack(vrna_fold_compound_t *fc, int i, FLT_OR_DBL energy, unsigned int options); ``` """ -function vrna_init_rand() - ccall((:vrna_init_rand, libRNA), Cvoid, ()) +function vrna_sc_add_stack(fc, i, energy, options) + ccall((:vrna_sc_add_stack, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, FLT_OR_DBL, Cuint), fc, i, energy, options) end """ - vrna_init_rand_seed(seed) - - @brief Initialize the random number generator with a pre-defined seed + vrna_sc_add_stack_comparative(fc, i, energies, options) - @see vrna_init_rand(), vrna_urn() - @param seed The seed for the random number generator ### Prototype ```c -void vrna_init_rand_seed(unsigned int seed); +int vrna_sc_add_stack_comparative(vrna_fold_compound_t *fc, int i, const FLT_OR_DBL *energies, unsigned int options); ``` """ -function vrna_init_rand_seed(seed) - ccall((:vrna_init_rand_seed, libRNA), Cvoid, (Cuint,), seed) +function vrna_sc_add_stack_comparative(fc, i, energies, options) + ccall((:vrna_sc_add_stack_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Cint, Ptr{FLT_OR_DBL}, Cuint), fc, i, energies, options) end """ - vrna_urn() + vrna_sc_remove(fc) - @brief get a random number from [0..1] + @brief Remove soft constraints from #vrna_fold_compound_t - @note Usually implemented by calling @e erand48(). + @note Accepts vrna_fold_compound_t of type #VRNA_FC_TYPE_SINGLE and #VRNA_FC_TYPE_COMPARATIVE - @see vrna_int_urn(), vrna_init_rand(), vrna_init_rand_seed() + @ingroup soft_constraints - @return A random number in range [0..1] + @param fc The #vrna_fold_compound_t possibly containing soft constraints ### Prototype ```c -double vrna_urn(void); +void vrna_sc_remove(vrna_fold_compound_t *fc); ``` """ -function vrna_urn() - ccall((:vrna_urn, libRNA), Cdouble, ()) +function vrna_sc_remove(fc) + ccall((:vrna_sc_remove, libRNA), Cvoid, (Ptr{vrna_fold_compound_t},), fc) end """ - vrna_int_urn(from, to) + vrna_sc_free(sc) - @brief Generates a pseudo random integer in a specified range + @brief Free memory occupied by a #vrna_sc_t data structure - @see vrna_urn(), vrna_init_rand() + @ingroup soft_constraints - @param from The first number in range - @param to The last number in range - @return A pseudo random number in range [from, to] + @param sc The data structure to free from memory ### Prototype ```c -int vrna_int_urn(int from, int to); +void vrna_sc_free(vrna_sc_t *sc); ``` """ -function vrna_int_urn(from, to) - ccall((:vrna_int_urn, libRNA), Cint, (Cint, Cint), from, to) +function vrna_sc_free(sc) + ccall((:vrna_sc_free, libRNA), Cvoid, (Ptr{vrna_sc_t},), sc) end """ - vrna_time_stamp() + vrna_sc_add_data(fc, data, free_data) - @brief Get a timestamp + @brief Add an auxiliary data structure for the generic soft constraints callback function - Returns a string containing the current date in the format - @verbatim Fri Mar 19 21:10:57 1993 @endverbatim + @ingroup soft_constraints - @return A string containing the timestamp + @see vrna_sc_add_f(), vrna_sc_add_exp_f(), vrna_sc_add_bt() + + @param fc The fold compound the generic soft constraint function should be bound to + @param data A pointer to the data structure that holds required data for function 'f' + @param free_data A pointer to a function that free's the memory occupied by @p data (Maybe NULL) + @return Non-zero on successful binding the data (and free-function), 0 otherwise ### Prototype ```c -char * vrna_time_stamp(void); +int vrna_sc_add_data(vrna_fold_compound_t *fc, void *data, vrna_auxdata_free_f free_data); ``` """ -function vrna_time_stamp() - ccall((:vrna_time_stamp, libRNA), Ptr{Cchar}, ()) +function vrna_sc_add_data(fc, data, free_data) + ccall((:vrna_sc_add_data, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_free_f), fc, data, free_data) end """ - get_input_line(string, 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 one to switch between different reading modes.\\n - Currently available options are:\\n - #VRNA_INPUT_COMMENT, #VRNA_INPUT_NOSKIP_COMMENTS, #VRNA_INPUT_NO_TRUNCATION - - pass a collection of options as one value like this: - @verbatim get_input_line(string, option_1 | option_2 | option_n) @endverbatim + vrna_sc_add_auxdata(fc, data, prepare_cb, free_cb) - 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:\\n - #VRNA_INPUT_FASTA_HEADER, #VRNA_INPUT_ERROR, #VRNA_INPUT_MISC, #VRNA_INPUT_QUIT - @param string A pointer to the character array that contains the line read - @param options A collection of options for switching the functions behavior - @return A flag with information about what has been read ### Prototype ```c -unsigned int get_input_line(char **string, unsigned int options); +int vrna_sc_add_auxdata(vrna_fold_compound_t *fc, void *data, vrna_auxdata_prepare_f prepare_cb, vrna_auxdata_free_f free_cb); ``` """ -function get_input_line(string, options) - ccall((:get_input_line, libRNA), Cuint, (Ptr{Ptr{Cchar}}, Cuint), string, options) +function vrna_sc_add_auxdata(fc, data, prepare_cb, free_cb) + ccall((:vrna_sc_add_auxdata, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cvoid}, vrna_auxdata_prepare_f, vrna_auxdata_free_f), fc, data, prepare_cb, free_cb) end """ - vrna_idx_row_wise(length) - - @brief 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 @verbatim (i,j) ~ iindx[i]-j @endverbatim - 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 ;) + vrna_sc_add_data_comparative(fc, data, free_data) - @see vrna_idx_col_wise() - @param length The length of the RNA sequence - @return The mapper array ### Prototype ```c -int * vrna_idx_row_wise(unsigned int length); +int vrna_sc_add_data_comparative(vrna_fold_compound_t *fc, void **data, vrna_auxdata_free_f *free_data); ``` """ -function vrna_idx_row_wise(length) - ccall((:vrna_idx_row_wise, libRNA), Ptr{Cint}, (Cuint,), length) +function vrna_sc_add_data_comparative(fc, data, free_data) + ccall((:vrna_sc_add_data_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Ptr{Cvoid}}, Ptr{vrna_auxdata_free_f}), fc, data, free_data) end """ - vrna_idx_col_wise(length) - - @brief Get an index mapper array (indx) for accessing the energy matrices, e.g. in MFE related functions. + vrna_sc_add_f(fc, f) - Access of a position "(i,j)" is then accomplished by using @verbatim (i,j) ~ indx[j]+i @endverbatim - This function is necessary as most of the two-dimensional energy matrices are actually one-dimensional arrays throughout - the ViennaRNAPackage + @brief Bind a function pointer for generic soft constraint feature (MFE version) - Consult the implemented code to find out about the mapping formula ;) + 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 @f\$ \\hat{E} @f\$ in @f\$ dacal/mol @f\$, where @f\$ 1 dacal/mol = 10 cal/mol @f\$. - @see vrna_idx_row_wise() + @ingroup soft_constraints - @param length The length of the RNA sequence - @return The mapper array + @see vrna_sc_add_data(), vrna_sc_add_bt(), vrna_sc_add_exp_f() + @param fc The fold compound the generic soft constraint function should be bound to + @param f A pointer to the function that evaluates the generic soft constraint feature + @return Non-zero on successful binding the callback function, 0 otherwise ### Prototype ```c -int * vrna_idx_col_wise(unsigned int length); +int vrna_sc_add_f(vrna_fold_compound_t *fc, vrna_sc_f f); ``` """ -function vrna_idx_col_wise(length) - ccall((:vrna_idx_col_wise, libRNA), Ptr{Cint}, (Cuint,), length) +function vrna_sc_add_f(fc, f) + ccall((:vrna_sc_add_f, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_f), fc, f) end """ - vrna_message_input_seq_simple() + vrna_sc_multi_cb_add(fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) - @brief Print a line to @e stdout that asks for an input sequence - There will also be a ruler (scale line) printed that helps orientation of the sequence positions ### Prototype ```c -void vrna_message_input_seq_simple(void); +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); ``` """ -function vrna_message_input_seq_simple() - ccall((:vrna_message_input_seq_simple, libRNA), Cvoid, ()) +function vrna_sc_multi_cb_add(fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) + ccall((:vrna_sc_multi_cb_add, libRNA), Csize_t, (Ptr{vrna_fold_compound_t}, vrna_sc_direct_f, vrna_sc_exp_direct_f, Ptr{Cvoid}, vrna_auxdata_prepare_f, vrna_auxdata_free_f, Cuint), fc, cb, cb_exp, data, prepare_cb, free_cb, decomp_type) end """ - vrna_message_input_seq(s) - - @brief Print a line with a user defined string and a ruler to stdout. + vrna_sc_add_f_comparative(fc, f) - (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 - @param s A user defined string that will be printed to stdout ### Prototype ```c -void vrna_message_input_seq(const char *s); +int vrna_sc_add_f_comparative(vrna_fold_compound_t *fc, vrna_sc_f *f); ``` """ -function vrna_message_input_seq(s) - ccall((:vrna_message_input_seq, libRNA), Cvoid, (Ptr{Cchar},), s) +function vrna_sc_add_f_comparative(fc, f) + ccall((:vrna_sc_add_f_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_sc_f}), fc, f) end """ - vrna_message_input_msa(s) + vrna_sc_add_bt(fc, f) + + @brief Bind a backtracking function pointer for generic soft constraint feature + + 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. + @ingroup soft_constraints + + @see vrna_sc_add_data(), vrna_sc_add_f(), vrna_sc_add_exp_f() + @param fc The fold compound the generic soft constraint function should be bound to + @param f A pointer to the function that returns additional base pairs + @return Non-zero on successful binding the callback function, 0 otherwise ### Prototype ```c -void vrna_message_input_msa(const char *s); +int vrna_sc_add_bt(vrna_fold_compound_t *fc, vrna_sc_bt_f f); ``` """ -function vrna_message_input_msa(s) - ccall((:vrna_message_input_msa, libRNA), Cvoid, (Ptr{Cchar},), s) +function vrna_sc_add_bt(fc, f) + ccall((:vrna_sc_add_bt, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_bt_f), fc, f) end """ - get_indx(length) + vrna_sc_add_exp_f(fc, exp_f) + + @brief Bind a function pointer for generic soft constraint feature (PF version) + 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 @f\$ \\hat{E} @f\$ as Boltzmann factor, i.e. @f\$ exp(- \\hat{E} / kT) @f\$. + The required unit for @f\$ E @f\$ is @f\$ cal/mol @f\$. + + @ingroup soft_constraints + + @see vrna_sc_add_bt(), vrna_sc_add_f(), vrna_sc_add_data() + @param fc The fold compound the generic soft constraint function should be bound to + @param exp_f A pointer to the function that evaluates the generic soft constraint feature + @return Non-zero on successful binding the callback function, 0 otherwise ### Prototype ```c -; +int vrna_sc_add_exp_f(vrna_fold_compound_t *fc, vrna_sc_exp_f exp_f); ``` """ -function get_indx(length) - ccall((:get_indx, libRNA), Ptr{Cint}, (Cuint,), length) +function vrna_sc_add_exp_f(fc, exp_f) + ccall((:vrna_sc_add_exp_f, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_exp_f), fc, exp_f) end """ - get_iindx(length) + vrna_sc_add_exp_f_comparative(fc, exp_f) ### Prototype ```c -; +int vrna_sc_add_exp_f_comparative(vrna_fold_compound_t *fc, vrna_sc_exp_f *exp_f); ``` """ -function get_iindx(length) - ccall((:get_iindx, libRNA), Ptr{Cint}, (Cuint,), length) +function vrna_sc_add_exp_f_comparative(fc, exp_f) + ccall((:vrna_sc_add_exp_f_comparative, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{vrna_sc_exp_f}), fc, exp_f) end +mutable struct vrna_sc_mod_param_s end + """ - get_line(fp) + @brief Modified base parameter data structure + + @see vrna_sc_mod_read_from_jsonfile(), vrna_sc_mod_read_from_json(), + vrna_sc_mod() +""" +const vrna_sc_mod_param_t = Ptr{vrna_sc_mod_param_s} + +""" + vrna_sc_mod_read_from_jsonfile(filename, md) + @brief Parse and extract energy parameters for a modified base from a JSON file + @see vrna_sc_mod_read_from_json(), vrna_sc_mod_parameters_free(), vrna_sc_mod(), + @ref modified-bases-params + + @param filename The JSON file containing the specifications of the modified base + @param md A model-details data structure (for look-up of canonical base pairs) + @return Parameters of the modified base ### Prototype ```c -; +vrna_sc_mod_param_t vrna_sc_mod_read_from_jsonfile(const char *filename, vrna_md_t *md); ``` """ -function get_line(fp) - ccall((:get_line, libRNA), Ptr{Cchar}, (Ptr{Libc.FILE},), fp) +function vrna_sc_mod_read_from_jsonfile(filename, md) + ccall((:vrna_sc_mod_read_from_jsonfile, libRNA), vrna_sc_mod_param_t, (Ptr{Cchar}, Ptr{vrna_md_t}), filename, md) end """ - print_tty_input_seq() + vrna_sc_mod_read_from_json(json, md) + + @brief Parse and extract energy parameters for a modified base from a JSON string + @see vrna_sc_mod_read_from_jsonfile(), vrna_sc_mod_parameters_free(), vrna_sc_mod(), + @ref modified-bases-params + @param filename The JSON file containing the specifications of the modified base + @param md A model-details data structure (for look-up of canonical base pairs) + @return Parameters of the modified base ### Prototype ```c -; +vrna_sc_mod_param_t vrna_sc_mod_read_from_json(const char *json, vrna_md_t *md); ``` """ -function print_tty_input_seq() - ccall((:print_tty_input_seq, libRNA), Cvoid, ()) +function vrna_sc_mod_read_from_json(json, md) + ccall((:vrna_sc_mod_read_from_json, libRNA), vrna_sc_mod_param_t, (Ptr{Cchar}, Ptr{vrna_md_t}), json, md) end """ - print_tty_input_seq_str(s) + vrna_sc_mod_parameters_free(params) + @brief Release memory occupied by a modified base parameter data structure + Properly free a #vrna_sc_mod_param_t data structure + + @param params The data structure to free ### Prototype ```c -; +void vrna_sc_mod_parameters_free(vrna_sc_mod_param_t params); ``` """ -function print_tty_input_seq_str(s) - ccall((:print_tty_input_seq_str, libRNA), Cvoid, (Ptr{Cchar},), s) +function vrna_sc_mod_parameters_free(params) + ccall((:vrna_sc_mod_parameters_free, libRNA), Cvoid, (vrna_sc_mod_param_t,), params) end """ - warn_user(message) + vrna_sc_mod_json(fc, json, modification_sites, options) + + @brief Prepare soft constraint callbacks for modified base as specified in JSON string + This function prepares all requirements to acknowledge modified bases as specified + in the provided @p json string. All subsequent predictions will treat each + modification site special and adjust energy contributions if necessary. + @see vrna_sc_mod_jsonfile(), vrna_sc_mod(), vrna_sc_mod_m6A(), + vrna_sc_mod_pseudouridine(), vrna_sc_mod_inosine(), + vrna_sc_mod_7DA(), vrna_sc_mod_purine(), vrna_sc_mod_dihydrouridine(), + #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT, + @ref modified-bases-params + + @param fc The fold_compound the corrections should be bound to + @param json The JSON formatted string with the modified base parameters + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_json(vrna_fold_compound_t *fc, const char *json, const unsigned int *modification_sites, unsigned int options); ``` """ -function warn_user(message) - ccall((:warn_user, libRNA), Cvoid, (Ptr{Cchar},), message) +function vrna_sc_mod_json(fc, json, modification_sites, options) + ccall((:vrna_sc_mod_json, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Cuint}, Cuint), fc, json, modification_sites, options) end """ - nrerror(message) + vrna_sc_mod_jsonfile(fc, json_file, modification_sites, options) + + @brief Prepare soft constraint callbacks for modified base as specified in JSON string + Similar to vrna_sc_mod_json(), this function prepares all requirements to + acknowledge modified bases as specified in the provided @p json file. + All subsequent predictions will treat each + modification site special and adjust energy contributions if necessary. + @see vrna_sc_mod_json(), vrna_sc_mod(), vrna_sc_mod_m6A(), + vrna_sc_mod_pseudouridine(), vrna_sc_mod_inosine(), + vrna_sc_mod_7DA(), vrna_sc_mod_purine(), vrna_sc_mod_dihydrouridine(), + #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT, + @ref modified-bases-params + + @param fc The fold_compound the corrections should be bound to + @param json The JSON formatted string with the modified base parameters + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_jsonfile(vrna_fold_compound_t *fc, const char *json_file, const unsigned int *modification_sites, unsigned int options); ``` """ -function nrerror(message) - ccall((:nrerror, libRNA), Cvoid, (Ptr{Cchar},), message) +function vrna_sc_mod_jsonfile(fc, json_file, modification_sites, options) + ccall((:vrna_sc_mod_jsonfile, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cchar}, Ptr{Cuint}, Cuint), fc, json_file, modification_sites, options) end """ - space(size) + vrna_sc_mod(fc, params, modification_sites, options) + + @brief Prepare soft constraint callbacks for modified base as specified in JSON string + This function takes a #vrna_sc_mod_param_t data structure as obtained + from vrna_sc_mod_read_from_json() or vrna_sc_mod_read_from_jsonfile() + and prepares all requirements to acknowledge modified bases as specified + in the provided @p params data structure. + All subsequent predictions will treat each + modification site special and adjust energy contributions if necessary. + @see vrna_sc_mod_read_from_json(), vrna_sc_mod_read_from_jsonfile(), + vrna_sc_mod_json(), vrna_sc_mod_jsonfile(), vrna_sc_mod_m6A(), + vrna_sc_mod_pseudouridine(), vrna_sc_mod_inosine(), + vrna_sc_mod_7DA(), vrna_sc_mod_purine(), vrna_sc_mod_dihydrouridine() + #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param json The JSON formatted string with the modified base parameters + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod(vrna_fold_compound_t *fc, const vrna_sc_mod_param_t params, const unsigned int *modification_sites, unsigned int options); ``` """ -function space(size) - ccall((:space, libRNA), Ptr{Cvoid}, (Cuint,), size) +function vrna_sc_mod(fc, params, modification_sites, options) + ccall((:vrna_sc_mod, libRNA), Cint, (Ptr{vrna_fold_compound_t}, vrna_sc_mod_param_t, Ptr{Cuint}, Cuint), fc, params, modification_sites, options) end """ - xrealloc(p, size) + vrna_sc_mod_m6A(fc, modification_sites, options) + + @brief Add soft constraint callbacks for N6-methyl-adenosine (m6A) + This is a convenience wrapper to add support for m6A using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from @rstinline :cite:t:`kierzek:2022` @endrst. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_m6A(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function xrealloc(p, size) - ccall((:xrealloc, libRNA), Ptr{Cvoid}, (Ptr{Cvoid}, Cuint), p, size) +function vrna_sc_mod_m6A(fc, modification_sites, options) + ccall((:vrna_sc_mod_m6A, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end """ - init_rand() + vrna_sc_mod_pseudouridine(fc, modification_sites, options) + + @brief Add soft constraint callbacks for Pseudouridine + This is a convenience wrapper to add support for pseudouridine using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from @rstinline :cite:t:`hudson:2013` @endrst. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_pseudouridine(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function init_rand() - ccall((:init_rand, libRNA), Cvoid, ()) +function vrna_sc_mod_pseudouridine(fc, modification_sites, options) + ccall((:vrna_sc_mod_pseudouridine, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end """ - urn() + vrna_sc_mod_inosine(fc, modification_sites, options) + + @brief Add soft constraint callbacks for Inosine + This is a convenience wrapper to add support for inosine using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from @rstinline :cite:t:`wright:2007` @endrst and @rstinline :cite:t:`wright:2018` @endrst. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_inosine(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function urn() - ccall((:urn, libRNA), Cdouble, ()) +function vrna_sc_mod_inosine(fc, modification_sites, options) + ccall((:vrna_sc_mod_inosine, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end """ - int_urn(from, to) + vrna_sc_mod_7DA(fc, modification_sites, options) + + @brief Add soft constraint callbacks for 7-deaza-adenosine (7DA) + This is a convenience wrapper to add support for 7-deaza-adenosine using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from @rstinline :cite:t:`richardson:2016` @endrst. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_7DA(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function int_urn(from, to) - ccall((:int_urn, libRNA), Cint, (Cint, Cint), from, to) +function vrna_sc_mod_7DA(fc, modification_sites, options) + ccall((:vrna_sc_mod_7DA, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end """ - filecopy(from, to) + vrna_sc_mod_purine(fc, modification_sites, options) + + @brief Add soft constraint callbacks for Purine (a.k.a. nebularine) + This is a convenience wrapper to add support for Purine using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from @rstinline :cite:t:`jolley:2017` @endrst. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_purine(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function filecopy(from, to) - ccall((:filecopy, libRNA), Cvoid, (Ptr{Libc.FILE}, Ptr{Libc.FILE}), from, to) +function vrna_sc_mod_purine(fc, modification_sites, options) + ccall((:vrna_sc_mod_purine, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end """ - time_stamp() + vrna_sc_mod_dihydrouridine(fc, modification_sites, options) + + @brief Add soft constraint callbacks for dihydrouridine + This is a convenience wrapper to add support for dihydrouridine using the + soft constraint callback mechanism. Modification sites are provided + as a list of sequence positions (1-based). Energy parameter corrections + are derived from Rosetta/RECESS predictions. + @see #VRNA_SC_MOD_CHECK_FALLBACK, #VRNA_SC_MOD_CHECK_UNMOD, #VRNA_SC_MOD_SILENT, + #VRNA_SC_MOD_DEFAULT + + @param fc The fold_compound the corrections should be bound to + @param modification_sites A list of modification site, i.e. positions that contain the modified base (1-based, last element in the list indicated by 0) + @param options A bitvector of options how to handle the input, e.g. #VRNA_SC_MOD_DEFAULT + @return Number of sequence positions modified base parameters will be used for ### Prototype ```c -; +int vrna_sc_mod_dihydrouridine(vrna_fold_compound_t *fc, const unsigned int *modification_sites, unsigned int options); ``` """ -function time_stamp() - ccall((:time_stamp, libRNA), Ptr{Cchar}, ()) +function vrna_sc_mod_dihydrouridine(fc, modification_sites, options) + ccall((:vrna_sc_mod_dihydrouridine, libRNA), Cint, (Ptr{vrna_fold_compound_t}, Ptr{Cuint}, Cuint), fc, modification_sites, options) end const GASCONST = 1.98717 @@ -12206,114 +12767,6 @@ const VRNA_SEQUENCE_RNA = Cuint(1) const VRNA_SEQUENCE_DNA = Cuint(2) -const VRNA_CONSTRAINT_FILE = 0 - -const VRNA_CONSTRAINT_SOFT_MFE = 0 - -const VRNA_OPTION_PF = 1 << 1 - -const VRNA_CONSTRAINT_SOFT_PF = VRNA_OPTION_PF - -const VRNA_DECOMP_PAIR_HP = Cuchar(1) - -const VRNA_DECOMP_PAIR_IL = Cuchar(2) - -const VRNA_DECOMP_PAIR_ML = Cuchar(3) - -const VRNA_DECOMP_PAIR_ML_EXT = Cuchar(23) - -const VRNA_DECOMP_PAIR_ML_OUTSIDE = Cuchar(4) - -const VRNA_DECOMP_ML_ML_ML = Cuchar(5) - -const VRNA_DECOMP_ML_STEM = Cuchar(6) - -const VRNA_DECOMP_ML_ML = Cuchar(7) - -const VRNA_DECOMP_ML_UP = Cuchar(8) - -const VRNA_DECOMP_ML_ML_STEM = Cuchar(9) - -const VRNA_DECOMP_ML_COAXIAL = Cuchar(10) - -const VRNA_DECOMP_ML_COAXIAL_ENC = Cuchar(11) - -const VRNA_DECOMP_EXT_EXT = Cuchar(12) - -const VRNA_DECOMP_EXT_UP = Cuchar(13) - -const VRNA_DECOMP_EXT_STEM = Cuchar(14) - -const VRNA_DECOMP_EXT_EXT_EXT = Cuchar(15) - -const VRNA_DECOMP_EXT_STEM_EXT = Cuchar(16) - -const VRNA_DECOMP_EXT_STEM_OUTSIDE = Cuchar(17) - -const VRNA_DECOMP_EXT_EXT_STEM = Cuchar(18) - -const VRNA_DECOMP_EXT_EXT_STEM1 = Cuchar(19) - -const VRNA_DECOMP_EXT_STEM_EXT1 = Cuchar(20) - -const VRNA_DECOMP_EXT_L = Cuchar(21) - -const VRNA_DECOMP_EXT_EXT_L = Cuchar(22) - -const VRNA_DECOMP_TYPES_MAX = 32 - -const VRNA_CONSTRAINT_NO_HEADER = 0 - -const VRNA_CONSTRAINT_DB = Cuint(16384) - -const VRNA_CONSTRAINT_DB_ENFORCE_BP = Cuint(32768) - -const VRNA_CONSTRAINT_DB_PIPE = Cuint(65536) - -const VRNA_CONSTRAINT_DB_DOT = Cuint(131072) - -const VRNA_CONSTRAINT_DB_X = Cuint(262144) - -const VRNA_CONSTRAINT_DB_ANG_BRACK = Cuint(524288) - -const VRNA_CONSTRAINT_DB_RND_BRACK = Cuint(1048576) - -const VRNA_CONSTRAINT_DB_INTRAMOL = Cuint(2097152) - -const VRNA_CONSTRAINT_DB_INTERMOL = Cuint(4194304) - -const VRNA_CONSTRAINT_DB_GQUAD = Cuint(8388608) - -const VRNA_CONSTRAINT_DB_CANONICAL_BP = Cuint(16777216) - -const VRNA_CONSTRAINT_DB_WUSS = Cuint(33554432) - -const VRNA_CONSTRAINT_DB_DEFAULT = (((((((VRNA_CONSTRAINT_DB | VRNA_CONSTRAINT_DB_PIPE) | VRNA_CONSTRAINT_DB_DOT) | VRNA_CONSTRAINT_DB_X) | VRNA_CONSTRAINT_DB_ANG_BRACK) | VRNA_CONSTRAINT_DB_RND_BRACK) | VRNA_CONSTRAINT_DB_INTRAMOL) | VRNA_CONSTRAINT_DB_INTERMOL) | VRNA_CONSTRAINT_DB_GQUAD - -const VRNA_CONSTRAINT_CONTEXT_EXT_LOOP = Cuchar(0x01) - -const VRNA_CONSTRAINT_CONTEXT_HP_LOOP = Cuchar(0x02) - -const VRNA_CONSTRAINT_CONTEXT_INT_LOOP = Cuchar(0x04) - -const VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC = Cuchar(0x08) - -const VRNA_CONSTRAINT_CONTEXT_MB_LOOP = Cuchar(0x10) - -const VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC = Cuchar(0x20) - -const VRNA_CONSTRAINT_CONTEXT_ENFORCE = Cuchar(0x40) - -const VRNA_CONSTRAINT_CONTEXT_NO_REMOVE = Cuchar(0x80) - -const VRNA_CONSTRAINT_CONTEXT_NONE = Cuchar(0) - -const VRNA_CONSTRAINT_CONTEXT_CLOSING_LOOPS = Cuchar(((VRNA_CONSTRAINT_CONTEXT_EXT_LOOP | VRNA_CONSTRAINT_CONTEXT_HP_LOOP) | VRNA_CONSTRAINT_CONTEXT_INT_LOOP) | VRNA_CONSTRAINT_CONTEXT_MB_LOOP) - -const VRNA_CONSTRAINT_CONTEXT_ENCLOSED_LOOPS = Cuchar(VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC | VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC) - -const VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS = Cuchar(VRNA_CONSTRAINT_CONTEXT_CLOSING_LOOPS | VRNA_CONSTRAINT_CONTEXT_ENCLOSED_LOOPS) - const VRNA_BRACKETS_ALPHA = Cuint(4) const VRNA_BRACKETS_RND = Cuint(8) @@ -12396,6 +12849,8 @@ const VRNA_OPTION_DEFAULT = Cuint(0) const VRNA_OPTION_MFE = 1 << 0 +const VRNA_OPTION_PF = 1 << 1 + const VRNA_OPTION_HYBRID = 1 << 2 const VRNA_OPTION_EVAL_ONLY = 1 << 3 @@ -12490,6 +12945,120 @@ const VRNA_INPUT_NOSKIP_COMMENTS = Cuint(128) const VRNA_INPUT_COMMENT = Cuint(8192) +const VRNA_CONSTRAINT_FILE = 0 + +const VRNA_CONSTRAINT_SOFT_MFE = 0 + +const VRNA_CONSTRAINT_SOFT_PF = VRNA_OPTION_PF + +const VRNA_DECOMP_PAIR_HP = Cuchar(1) + +const VRNA_DECOMP_PAIR_IL = Cuchar(2) + +const VRNA_DECOMP_PAIR_ML = Cuchar(3) + +const VRNA_DECOMP_PAIR_ML_EXT = Cuchar(23) + +const VRNA_DECOMP_PAIR_ML_OUTSIDE = Cuchar(4) + +const VRNA_DECOMP_ML_ML_ML = Cuchar(5) + +const VRNA_DECOMP_ML_STEM = Cuchar(6) + +const VRNA_DECOMP_ML_ML = Cuchar(7) + +const VRNA_DECOMP_ML_UP = Cuchar(8) + +const VRNA_DECOMP_ML_ML_STEM = Cuchar(9) + +const VRNA_DECOMP_ML_COAXIAL = Cuchar(10) + +const VRNA_DECOMP_ML_COAXIAL_ENC = Cuchar(11) + +const VRNA_DECOMP_EXT_EXT = Cuchar(12) + +const VRNA_DECOMP_EXT_UP = Cuchar(13) + +const VRNA_DECOMP_EXT_STEM = Cuchar(14) + +const VRNA_DECOMP_EXT_EXT_EXT = Cuchar(15) + +const VRNA_DECOMP_EXT_STEM_EXT = Cuchar(16) + +const VRNA_DECOMP_EXT_STEM_OUTSIDE = Cuchar(17) + +const VRNA_DECOMP_EXT_EXT_STEM = Cuchar(18) + +const VRNA_DECOMP_EXT_EXT_STEM1 = Cuchar(19) + +const VRNA_DECOMP_EXT_STEM_EXT1 = Cuchar(20) + +const VRNA_DECOMP_EXT_L = Cuchar(21) + +const VRNA_DECOMP_EXT_EXT_L = Cuchar(22) + +const VRNA_DECOMP_TYPES_MAX = 32 + +const VRNA_CONSTRAINT_NO_HEADER = 0 + +const VRNA_CONSTRAINT_DB = Cuint(16384) + +const VRNA_CONSTRAINT_DB_ENFORCE_BP = Cuint(32768) + +const VRNA_CONSTRAINT_DB_PIPE = Cuint(65536) + +const VRNA_CONSTRAINT_DB_DOT = Cuint(131072) + +const VRNA_CONSTRAINT_DB_X = Cuint(262144) + +const VRNA_CONSTRAINT_DB_ANG_BRACK = Cuint(524288) + +const VRNA_CONSTRAINT_DB_RND_BRACK = Cuint(1048576) + +const VRNA_CONSTRAINT_DB_INTRAMOL = Cuint(2097152) + +const VRNA_CONSTRAINT_DB_INTERMOL = Cuint(4194304) + +const VRNA_CONSTRAINT_DB_GQUAD = Cuint(8388608) + +const VRNA_CONSTRAINT_DB_CANONICAL_BP = Cuint(16777216) + +const VRNA_CONSTRAINT_DB_WUSS = Cuint(33554432) + +const VRNA_CONSTRAINT_DB_DEFAULT = (((((((VRNA_CONSTRAINT_DB | VRNA_CONSTRAINT_DB_PIPE) | VRNA_CONSTRAINT_DB_DOT) | VRNA_CONSTRAINT_DB_X) | VRNA_CONSTRAINT_DB_ANG_BRACK) | VRNA_CONSTRAINT_DB_RND_BRACK) | VRNA_CONSTRAINT_DB_INTRAMOL) | VRNA_CONSTRAINT_DB_INTERMOL) | VRNA_CONSTRAINT_DB_GQUAD + +const VRNA_CONSTRAINT_CONTEXT_EXT_LOOP = Cuchar(0x01) + +const VRNA_CONSTRAINT_CONTEXT_HP_LOOP = Cuchar(0x02) + +const VRNA_CONSTRAINT_CONTEXT_INT_LOOP = Cuchar(0x04) + +const VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC = Cuchar(0x08) + +const VRNA_CONSTRAINT_CONTEXT_MB_LOOP = Cuchar(0x10) + +const VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC = Cuchar(0x20) + +const VRNA_CONSTRAINT_CONTEXT_ENFORCE = Cuchar(0x40) + +const VRNA_CONSTRAINT_CONTEXT_NO_REMOVE = Cuchar(0x80) + +const VRNA_CONSTRAINT_CONTEXT_NONE = Cuchar(0) + +const VRNA_CONSTRAINT_CONTEXT_CLOSING_LOOPS = Cuchar(((VRNA_CONSTRAINT_CONTEXT_EXT_LOOP | VRNA_CONSTRAINT_CONTEXT_HP_LOOP) | VRNA_CONSTRAINT_CONTEXT_INT_LOOP) | VRNA_CONSTRAINT_CONTEXT_MB_LOOP) + +const VRNA_CONSTRAINT_CONTEXT_ENCLOSED_LOOPS = Cuchar(VRNA_CONSTRAINT_CONTEXT_INT_LOOP_ENC | VRNA_CONSTRAINT_CONTEXT_MB_LOOP_ENC) + +const VRNA_CONSTRAINT_CONTEXT_ALL_LOOPS = Cuchar(VRNA_CONSTRAINT_CONTEXT_CLOSING_LOOPS | VRNA_CONSTRAINT_CONTEXT_ENCLOSED_LOOPS) + +const VRNA_SC_MOD_CHECK_FALLBACK = 1 + +const VRNA_SC_MOD_CHECK_UNMOD = 2 + +const VRNA_SC_MOD_SILENT = 4 + +const VRNA_SC_MOD_DEFAULT = VRNA_SC_MOD_CHECK_FALLBACK | VRNA_SC_MOD_CHECK_UNMOD + # exports const PREFIXES = ["VRNA_", "vrna_"] for name in names(@__MODULE__; all=true), prefix in PREFIXES