Support for modified base energy params (sc_mod_*! functions) (#25)

* Initial implementation and tests for sc_mod_*! functions

* Fixes for julia-1.6

* docs: explain how to use modified base energy param presets

README.md

@@ -282,6 +282,33 @@ inverse_pf_fold("AAAAAAA", "((...))")  # => ("GCCAAGC", 2.0244526863098145 kcal
 ViennaRNA.init_rand_seed(42)
 ```
 
+### Modified bases energy parameter presets
+
+Energy parameters for modified bases can be used via ViennaRNA's soft
+constraints mechanism.
+
+```julia
+using ViennaRNA
+fc = FoldCompound("AAACCCUUU")
+partfn(fc)  # -0.0025467473022687203 kcal mol^-1
+ViennaRNA.sc_mod_pseudouridine!(fc, [7,8,9])  # modify positions 7, 8, 9
+partfn(fc)  # -0.004713416050703315 kcal mol^-1
+```
+
+These functions are currently available:
+```
+sc_mod_7DA!
+sc_mod_dihydrouridine!
+sc_mod_inosine!
+sc_mod_m6A!
+sc_mod_pseudouridine!
+sc_mod_purine!
+```
+Please refer to the
+[ViennaRNA section on modified bases](https://www.tbi.univie.ac.at/RNA/ViennaRNA/doc/html/modified_bases.html)
+for more details.
+
+
 ## Reducing memory usage
 
 When creating many `FoldCompound`s, running `finalize` manually will

src/wrappers.jl

@@ -47,6 +47,17 @@ const SAMPLE_STRUCTURES_OPTIONS = _makedict("VRNA_PBACKTRACK_")
 #     ...
 # )
 
+# data needed to auto-generate wrappers and tests for the
+# vrna_sc_mod_* convenience functions for specific base modifications
+const SC_MOD_PRESET_FUNCTIONS = [
+    (short="m6A",            desc="N6-methyl-adenosine (m6A)",  unmod_base="A"),
+    (short="pseudouridine",  desc="pseudouridine",              unmod_base="U"),
+    (short="inosine",        desc="inosine",                    unmod_base="G"),
+    (short="7DA",            desc="7-deaza-adenosine (7DA)",    unmod_base="A"),
+    (short="purine",         desc="Purine (a.k.a. nebularine)", unmod_base="A"),
+    (short="dihydrouridine", desc="dihydrouridine",             unmod_base="U"),
+]
+
 end # module Private
 import .Private
 
@@ -1140,6 +1151,38 @@ function sample_structures(sequence::AbstractString;
     return res
 end
 
+# soft constraints
+# modified bases via soft constraints functions (vrna_sc_mod_*)
+
+# sc_mod_*! functions for preset (built-in) energy params of modified
+# bases
+for modfn_data in Private.SC_MOD_PRESET_FUNCTIONS
+    short = modfn_data.short
+    desc = modfn_data.desc
+    func_name = Symbol("sc_mod_$(short)!")
+    vrna_func_name = Symbol("vrna_sc_mod_$short")
+    @eval begin
+        @doc """
+            $($func_name)(fc, modification_sites::Vector{<:Integer})
+
+        Apply base modifications for $($desc) at the
+        positions given by `modification_sites` via soft constraint callbacks.
+        """
+        function $func_name(fc::FoldCompound, modification_sites::Vector{T};
+                            option_flags=LibRNA.VRNA_SC_MOD_DEFAULT) where {T<:Integer}
+            # Note: ViennaRNA expects 1-based indexing for modification_sites
+            nsites = length(modification_sites)
+            sites = convert(Vector{Cuint}, modification_sites)
+            push!(sites, 0)  # array needs to be terminated by 0
+            nsites_mod = LibRNA.$vrna_func_name(fc.ptr, sites, option_flags)
+            if nsites_mod != nsites
+                throw(ArgumentError("Modified $nsites_mod positions but expected $nsites"))
+            end
+            return fc
+        end
+    end
+end
+
 # suboptimal structures
 
 """

test/wrappers.jl

@@ -563,6 +563,21 @@ end
 
 end
 
+@testset "sc_mod_*" begin
+    showtestset()
+    n = 5
+    for modfn_data in ViennaRNA.Private.SC_MOD_PRESET_FUNCTIONS
+        short = modfn_data.short
+        unmod_base = modfn_data.unmod_base
+        fc = FoldCompound(unmod_base^n)
+        func_name = Symbol("sc_mod_$(short)!")
+        @eval @test ViennaRNA.$func_name($fc, [1, $n]) isa FoldCompound
+        @eval @test_throws ArgumentError begin
+            ViennaRNA.$func_name($fc, [1, $n + 1]; option_flags=LibRNA.VRNA_SC_MOD_SILENT)
+        end
+    end
+end
+
 @testset "subopt" begin
     showtestset()
     seq = "GGGGGAAAAACCCCCCCCAUUCA"