Calculates melting temperature (Tm) from nearest-neighbor (NN) thermodynamics, summing the stacking enthalpies and entropies of adjacent base-pair steps and applying initiation, symmetry, salt and chemical corrections. Terminal mismatches, internal mismatches and dangling ends are supported through dedicated parameter tables. The function verifies that every dinucleotide step in the input sequence is present in the selected tables before calculating.
tm_nn(
gr_seq,
ambiguous = FALSE,
shift = 0,
nn_table = c("DNA_NN_SantaLucia_2004", "DNA_NN_Ghosh_2020_PEG200",
"DNA_NN_Breslauer_1986", "DNA_NN_Sugimoto_1996", "DNA_NN_Allawi_1998",
"RNA_NN_Freier_1986", "RNA_NN_Xia_1998", "RNA_NN_Chen_2012", "RNA_NN_Zuber_2022",
"RNA_NN_Ghosh_2023_PEG200", "RNA_DNA_NN_Sugimoto_1995", "DNA_NN_Weber_2015",
"DNA_NN_Weber_OW04_69", "DNA_NN_Weber_OW04_119", "DNA_NN_Weber_OW04_220",
"DNA_NN_Weber_OW04_621", "DNA_NN_Weber_OW04_1020", "RNA_NN_Weber_VIF_71",
"RNA_NN_Weber_VIF_121", "RNA_NN_Weber_VIF_221", "RNA_NN_Weber_VIF_621",
"RNA_NN_Weber_VIF_1021", "RNA_NN_Weber_FIF_71", "RNA_NN_Weber_FIF_121",
"RNA_NN_Weber_FIF_221", "RNA_NN_Weber_FIF_621", "RNA_NN_Weber_FIF_1021",
"RNA_DNA_NN_Weber_2019_FT", "RNA_DNA_NN_Weber_2019_VH", "RNA_DNA_NN_Weber_2019_LS",
"RNA_DNA_NN_Banerjee_2020"),
tmm_table = "DNA_TMM_Bommarito_2000",
imm_table = "DNA_IMM_Peyret_1999",
de_table = c("DNA_DE_Bommarito_2000", "RNA_DE_Turner_2010"),
dnac_high = 25,
dnac_low = 25,
self_comp = FALSE,
Na = 50,
K = 0,
Tris = 0,
Mg = 0,
dNTPs = 0,
salt_method = c("Schildkraut2010", "Wetmur1991", "SantaLucia1996", "SantaLucia1998-1",
"Owczarzy2004", "Owczarzy2008", "none"),
DMSO = 0,
formamide_unit = list(value = 0, unit = "percent"),
dmso_factor = 0.75,
formamide_factor = 0.65
)A TmCalculator list with:
grThe input GRanges with metadata columns Tm
and GC (melting temperature in \(^{\circ}\)C and GC percent).
Sequences that could not be evaluated receive NA.
optionsThe calculation parameters actually used, including
the parameter tables and their citations, ion and additive
concentrations, Salt correction method, and two fields recording
how salt was handled: Salt correction applied (logical) and
Parameter set fitted at [Na+] (mM), which is NA for
reference-salt sets. Regions skipped for containing N are listed
in Skipped regions containing N.
Pre-processed sequence(s) in 5' to 3' direction. This should be the output from to_genomic_ranges() function.
Logical value controlling how ambiguous bases are handled: - TRUE: Ambiguous bases (e.g., N, R, Y) are included in calculations - FALSE (default): Ambiguous bases are excluded from calculations
Integer value controlling the alignment offset between primer and template sequences. Visual representation of different shift values:
shift = 0 (default): Primer: 5' ATGCG 3' Template: 3' TACGC 5'
shift = -1: Primer: 5' ATGCG 3' Template: 3' TACGC 5' ^
shift = 1: Primer: 5' ATGCG 3' Template: 3' TACGC 5' ^
The shift parameter is necessary when: - Sequences have different lengths - Dangling ends are required - Specific alignment positions are needed
Thermodynamic nearest-neighbor parameters for different nucleic acid hybridizations. Parameter sets are listed below by hybridization type. Sets marked with a sodium concentration were fitted at that condition and are not salt-corrected further (see the "Choosing a parameter set" section).
DNA/DNA hybridizations, reference salt: - "DNA_NN_Breslauer_1986": Original DNA/DNA parameters - "DNA_NN_Sugimoto_1996": Improved DNA/DNA parameters - "DNA_NN_Allawi_1998": DNA/DNA parameters with internal mismatch corrections - "DNA_NN_SantaLucia_2004": Unified DNA/DNA parameters (default)
DNA/DNA hybridizations, melting-temperature optimized (Weber 2015): - "DNA_NN_Weber_2015": Combined dataset, 1020 mM. Recommended when a salt-optimized DNA set is wanted at high salt - "DNA_NN_Weber_OW04_69", "...119", "...220", "...621", "...1020": fitted independently at 69, 119, 220, 621 and 1020 mM sodium
DNA/DNA under molecular crowding (cell-like rather than dilute solution): - "DNA_NN_Ghosh_2020_PEG200": fitted in 40 wt
RNA/RNA hybridizations, reference salt: - "RNA_NN_Freier_1986": Original RNA/RNA parameters - "RNA_NN_Xia_1998": Improved RNA/RNA parameters - "RNA_NN_Chen_2012": Updated RNA/RNA parameters with GU pair corrections - "RNA_NN_Zuber_2022": Successor to Xia 1998 with improved end effects. The terminal-AU penalty is replaced by end terms that depend on the penultimate base pair, applied automatically from a companion table
RNA/RNA under molecular crowding (cell-like rather than dilute solution): - "RNA_NN_Ghosh_2023_PEG200": fitted in 40 wt and shown to describe duplexes in an intracellular cation composition
RNA/RNA hybridizations, salt-optimized (Ferreira 2019). VIF (variable initiation factors) gave better cross-validation than FIF (fixed): - "RNA_NN_Weber_VIF_71", "...121", "...221", "...621", "...1021" - "RNA_NN_Weber_FIF_71", "...121", "...221", "...621", "...1021"
RNA/DNA hybridizations: - "RNA_DNA_NN_Sugimoto_1995": RNA/DNA hybridization parameters - "RNA_DNA_NN_Weber_2019_FT": curve-fitting derived, 1000 mM. Best performing high-salt hybrid set in Basilio Barbosa (2019) - "RNA_DNA_NN_Weber_2019_VH": van't Hoff derived, 1000 mM - "RNA_DNA_NN_Weber_2019_LS": low salt, 100 mM - "RNA_DNA_NN_Banerjee_2020": improved hybrid parameters fitted at a physiological condition (100 mM NaCl), Banerjee et al. (2020)
Alternatively, supply a matrix or data.frame of parameters directly. This is the route for parameter sets the package does not ship, in particular sets covering modified bases such as 5-methylcytosine. Requirements:
numeric, with columns 1 and 2 read as delta H (kcal/mol) and delta S (cal/mol/K); further columns are ignored;
row names giving the parameter keys, e.g. "AA/TT",
"init", "init_A/T", "sym";
every key of a built-in reference set must be present. The
reference is named by attr(x, "reference"), or defaults to
the first built-in listed for the argument, which is a DNA/DNA set;
RNA and hybrid tables should therefore set the attribute. Extra keys
beyond the reference are kept, which is how a modified-base set adds
stacks rather than replacing them.
The supplied table is reordered to the reference key order before use, so that two tables differing only in row order give identical results. A missing key would otherwise contribute zero to the calculation instead of raising an error, which is why the full key set is required. Keys that disagree with their reverse complement produce a warning: expected for modified bases, a transposition error otherwise.
Two optional attributes are honoured. attr(x, "salt_mM") marks a
set as fitted at a stated sodium concentration, which suppresses the salt
correction at that concentration exactly as for the built-in sets fitted
this way; without it the table is treated as a reference-condition set and
salt_method is applied. attr(x, "end_table") supplies a
companion penultimate-pair end-effect table.
Thermodynamic parameters for terminal mismatches. Default: "DNA_TMM_Bommarito_2000" These parameters account for mismatches at the ends of the duplex.
Thermodynamic parameters for internal mismatches. Default: "DNA_IMM_Peyret_1999" These parameters account for mismatches within the duplex, including inosine mismatches.
Thermodynamic parameters for dangling ends. Default: "DNA_DE_Bommarito_2000" Available options: - "DNA_DE_Bommarito_2000": Parameters for DNA dangling ends - "RNA_DE_Turner_2010": Parameters for RNA dangling ends
Concentration of the higher concentrated strand in nM. Default: 25 Typically this is the primer (for PCR) or the probe concentration.
Concentration of the lower concentrated strand in nM. Default: 25 This is typically the template concentration.
Logical value indicating if the sequence is self-complementary: - TRUE: Sequence can bind to itself, dnac_low is ignored - FALSE (default): Sequence binds to a different complementary sequence
Millimolar concentration of sodium ions. Default: 50
Millimolar concentration of potassium ions. Default: 0
Millimolar concentration of Tris buffer. Default: 0
Millimolar concentration of magnesium ions. Default: 0
Millimolar concentration of deoxynucleotide triphosphates. Default: 0
Salt correction method. Options are:
Available options:
- "Schildkraut2010": Updated salt correction method
- "Wetmur1991": Classic salt correction method
- "SantaLucia1996": DNA-specific salt correction
- "SantaLucia1998-1": Improved DNA salt correction
- "Owczarzy2004": Comprehensive salt correction
- "Owczarzy2008": Updated comprehensive salt correction
- "none": Disables salt correction entirely
Note: Parameter sets fitted at a specific sodium concentration (those
carrying a "salt_mM" attribute, e.g. the Weber/VarGibbs series and
Banerjee 2020) already
account for salt. When the requested Na matches the concentration
such a set was fitted at, salt correction is skipped automatically; when
it does not, a warning is issued.
Percent DMSO concentration in the reaction mixture. Default: 0 DMSO can lower the melting temperature of nucleic acid duplexes.
Formamide concentration as `list(value, unit)`. Default: list(value = 0, unit = "percent") - value: numeric value of formamide concentration - unit: character string specifying the unit ("percent" or "molar") Default: list(value=0, unit="percent")
Coefficient of melting temperature (Tm) decrease per percent DMSO. Default: 0.75 (von Ahsen N, 2001, PMID:11673362) Other published values: 0.5, 0.6, 0.675
Coefficient of melting temperature (Tm) decrease per percent formamide. Default: 0.65 Literature reports values ranging from 0.6 to 0.72
Parameter sets fall into two families that are handled differently.
The two families are distinguished by one mechanical criterion: a set is
condition-specific if and only if it carries a salt_mM attribute.
Reference-salt sets (no salt_mM; Breslauer 1986,
Sugimoto 1996, Allawi 1998, SantaLucia 2004, Freier 1986, Xia 1998,
Chen 2012, Zuber 2022, Sugimoto 1995) were fitted at a single reference
sodium concentration, and other conditions are reached by applying one of
the salt_method correction formulas.
Condition-specific sets (the Weber/VarGibbs series, Banerjee 2020,
and the molecular-crowding sets of Ghosh 2020 and Ghosh 2023) were instead
fitted directly at a stated sodium concentration and are intended to
replace salt correction rather than be corrected. When the requested
Na matches the set's salt_mM value,
salt correction is skipped automatically; when it does not, the correction is
still applied but a warning is issued, since correcting an already
condition-specific set double-counts the ionic effect. Whether a correction
was applied is recorded in the returned options.
As a rule of thumb, pick the set whose fitted salt is closest to your experimental condition rather than correcting a distant one.
Junhui Li
DNA_NN_Breslauer_1986: Breslauer K J (1986) <doi:10.1073/pnas.83.11.3746>
DNA_NN_Sugimoto_1996: Sugimoto N (1996) <doi:10.1093/nar/24.22.4501>
DNA_NN_Allawi_1998: Allawi H (1998) <doi:10.1093/nar/26.11.2694>
DNA_NN_SantaLucia_2004: SantaLucia J (2004) <doi:10.1146/annurev.biophys.32.110601.141800>
RNA_NN_Freier_1986: Freier S (1986) <doi:10.1073/pnas.83.24.9373>
RNA_NN_Xia_1998: Xia T (1998) <doi:10.1021/bi9809425>
RNA_NN_Chen_2012: Chen JL (2012) <doi:10.1021/bi3002709>
RNA_DNA_NN_Sugimoto_1995: Sugimoto N (1995)<doi:10.1016/S0048-9697(98)00088-6>
The following sets were derived by melting-temperature optimization and are fitted at the sodium concentration given in parentheses. They are not salt-corrected further; see the “Choosing a parameter set” section.
DNA_NN_Weber_2015 (1020 mM): Weber G (2015) <doi:10.1093/bioinformatics/btu751>
DNA_NN_Weber_OW04_69 (69 mM), DNA_NN_Weber_OW04_119 (119 mM), DNA_NN_Weber_OW04_220 (220 mM), DNA_NN_Weber_OW04_621 (621 mM), DNA_NN_Weber_OW04_1020 (1020 mM): Weber G (2015) <doi:10.1093/bioinformatics/btu751>
RNA_NN_Weber_VIF_71 (71 mM), RNA_NN_Weber_VIF_121 (121 mM), RNA_NN_Weber_VIF_221 (221 mM), RNA_NN_Weber_VIF_621 (621 mM), RNA_NN_Weber_VIF_1021 (1021 mM): Ferreira I (2019) <doi:10.1016/j.chemphys.2019.01.016>, variable initiation factors
RNA_NN_Weber_FIF_71 (71 mM), RNA_NN_Weber_FIF_121 (121 mM), RNA_NN_Weber_FIF_221 (221 mM), RNA_NN_Weber_FIF_621 (621 mM), RNA_NN_Weber_FIF_1021 (1021 mM): Ferreira I (2019) <doi:10.1016/j.chemphys.2019.01.016>, fixed initiation factors
RNA_DNA_NN_Weber_2019_FT (1000 mM), RNA_DNA_NN_Weber_2019_VH (1000 mM), RNA_DNA_NN_Weber_2019_LS (100 mM): Basilio Barbosa V (2019) <doi:10.1016/j.bpc.2019.106189>
RNA_DNA_NN_Banerjee_2020 (100 mM): Banerjee D (2020) <doi:10.1093/nar/gkaa572>
RNA_NN_Zuber_2022: Zuber J (2022) <doi:10.1093/nar/gkac261>
RNA_NN_Ghosh_2023_PEG200 (100 mM, 40 wt
DNA_NN_Ghosh_2020_PEG200 (100 mM, 40 wt
DNA_TMM_Bommarito_2000: Bommarito S (2000) <doi:10.1093/nar/28.9.1929>
DNA_IMM_Peyret_1999: Peyret N (1999) <doi:10.1021/bi9825091> & Allawi H T (1997) <doi:10.1021/bi962590c> & Santalucia N (2005) <doi:10.1093/nar/gki918>
DNA_DE_Bommarito_2000: Bommarito S (2000) <doi:10.1093/nar/28.9.1929>
RNA_DE_Turner_2010: Turner D H (2010) <doi:10.1093/nar/gkp892>
Breslauer K J , Frank R , Blocker H , et al. Predicting DNA duplex stability from the base sequence.[J]. Proceedings of the National Academy of Sciences, 1986, 83(11):3746-3750.
Sugimoto N , Nakano S , Yoneyama M , et al. Improved Thermodynamic Parameters and Helix Initiation Factor to Predict Stability of DNA Duplexes[J]. Nucleic Acids Research, 1996, 24(22):4501-5.
Allawi, H. Thermodynamics of internal C.T mismatches in DNA[J]. Nucleic Acids Research, 1998, 26(11):2694-2701.
Hicks L D , Santalucia J . The thermodynamics of DNA structural motifs.[J]. Annual Review of Biophysics & Biomolecular Structure, 2004, 33(1):415-440.
Freier S M , Kierzek R , Jaeger J A , et al. Improved free-energy parameters for predictions of RNA duplex stability.[J]. Proceedings of the National Academy of Sciences, 1986, 83(24):9373-9377.
Xia T , Santalucia , J , Burkard M E , et al. Thermodynamic Parameters for an Expanded Nearest-Neighbor Model for Formation of RNA Duplexes with Watson-Crick Base Pairs,[J]. Biochemistry, 1998, 37(42):14719-14735.
Chen J L , Dishler A L , Kennedy S D , et al. Testing the Nearest Neighbor Model for Canonical RNA Base Pairs: Revision of GU Parameters[J]. Biochemistry, 2012, 51(16):3508-3522.
Bommarito S, Peyret N, Jr S L. Thermodynamic parameters for DNA sequences with dangling ends[J]. Nucleic Acids Research, 2000, 28(9):1929-1934.
Turner D H , Mathews D H . NNDB: the nearest neighbor parameter database for predicting stability of nucleic acid secondary structure[J]. Nucleic Acids Research, 2010, 38(Database issue):D280-D282.
Sugimoto N , Nakano S I , Katoh M , et al. Thermodynamic Parameters To Predict Stability of RNA/DNA Hybrid Duplexes[J]. Biochemistry, 1995, 34(35):11211-11216.
Allawi H, SantaLucia J: Thermodynamics and NMR of internal G-T mismatches in DNA. Biochemistry 1997, 36:10581-10594.
Weber G. Optimization method for obtaining nearest-neighbour DNA entropies and enthalpies directly from melting temperatures. Bioinformatics, 2015, 31(6):871-877.
Ferreira I, Jolley E A, Znosko B M, Weber G. Replacing salt correction factors with optimized RNA nearest-neighbour enthalpy and entropy parameters. Chemical Physics, 2019, 521:69-76.
Basilio Barbosa V, de Oliveira Martins E, Weber G. Nearest-neighbour parameters optimized for melting temperature prediction of DNA/RNA hybrids at high and low salt concentrations. Biophysical Chemistry, 2019, 251:106189.
Banerjee D, Tateishi-Karimata H, Ohyama T, et al. Improved nearest-neighbor parameters for the stability of RNA/DNA hybrids under a physiological condition. Nucleic Acids Research, 2020, 48(21):12042-12054.
Zuber J, Schroeder S J, Sun H, Turner D H, Mathews D H. Nearest neighbor rules for RNA helix folding thermodynamics: improved end effects. Nucleic Acids Research, 2022, 50(9):5251-5262.
Ghosh S, Takahashi S, Ohyama T, et al. Nearest-neighbor parameters for predicting DNA duplex stability in diverse molecular crowding conditions. Proceedings of the National Academy of Sciences, 2020, 117(25):14194-14201.
Ghosh S, Takahashi S, Banerjee D, et al. Nearest-neighbor parameters for the prediction of RNA duplex stability in diverse in vitro and cellular-like crowding conditions. Nucleic Acids Research, 2023, 51(9):4101-4111.
Santalucia N E W J . Nearest-neighbor thermodynamics of deoxyinosine pairs in DNA duplexes[J]. Nucleic Acids Research, 2005, 33(19):6258-67.
Peyret N , Seneviratne P A , Allawi H T , et al. Nearest-Neighbor Thermodynamics and NMR of DNA Sequences with Internal A-A, C-C, G-G, and T-T Mismatches, [J]. Biochemistry, 1999, 38(12):3468-3477.
Weber G. Optimization method for obtaining nearest-neighbour DNA entropies and enthalpies directly from melting temperatures[J]. Bioinformatics, 2015, 31(6):871-877.
Ferreira I, Jolley E A, Znosko B M, et al. Replacing salt correction factors with optimized RNA nearest-neighbour enthalpy and entropy parameters[J]. Chemical Physics, 2019, 521:69-76.
Basilio Barbosa V, de Oliveira Martins E, Weber G. Nearest-neighbour parameters optimized for melting temperature prediction of DNA/RNA hybrids at high and low salt concentrations[J]. Biophysical Chemistry, 2019, 251:106189.
Banerjee D, Tateishi-Karimata H, Ohyama T, Ghosh S, Endoh T, Takahashi S, Sugimoto N. Improved nearest-neighbor parameters for the stability of RNA/DNA hybrids under a physiological condition[J]. Nucleic Acids Research, 2020, 48(21):12042-12054.
Zuber J, Schroeder S J, Sun H, Turner D H, Mathews D H. Nearest neighbor rules for RNA helix folding thermodynamics: improved end effects[J]. Nucleic Acids Research, 2022, 50(9):5251-5262.
Ghosh S, Takahashi S, Banerjee D, Ohyama T, Endoh T, Tateishi-Karimata H, Sugimoto N. Nearest-neighbor parameters for the prediction of RNA duplex stability in diverse in vitro and cellular-like crowding conditions[J]. Nucleic Acids Research, 2023, 51(9):4101-4111.
Ghosh S, Takahashi S, Ohyama T, Endoh T, Tateishi-Karimata H, Sugimoto N. Nearest-neighbor parameters for predicting DNA duplex stability in diverse molecular crowding conditions[J]. Proceedings of the National Academy of Sciences, 2020, 117(25):14194-14201.
tm_calculate for a single entry point to the
nearest-neighbor, GC-content and Wallace methods.
input_seq <- c("AAAATTTTTTTCCCCCCCCCCCCCCGGGGGGGGGGGGTGTGCGCTGC",
"AAAATTTTTTTCCCCCCCCCCCCCCGGGGGGGGGGGGTGTGCGCTGC")
seqs <- to_genomic_ranges(input_seq)
out <- tm_nn(seqs, Na=50)
out
# A parameter set fitted at a stated sodium concentration. Because Na
# matches the concentration the set was fitted at, salt correction is
# skipped automatically rather than applied on top of it.
out_ls <- tm_nn(seqs, nn_table = "RNA_DNA_NN_Weber_2019_LS", Na = 100)
out_ls$options[["Salt correction applied"]]
# -- A parameter table supplied by the user --------------------------------
# Any of nn_table, tmm_table, imm_table and de_table also accepts a matrix,
# which is how a set the package does not ship, most obviously one covering
# modified bases, is used without waiting for a new release.
#
# Start from a built-in set to get the required keys, then add a stack. The
# key naming follows the built-in convention: top strand, "/", bottom
# strand, so "MG/CG" would be a 5-methylcytosine followed by G, paired with
# CG. The values here are illustrative and are NOT measured parameters.
tbl <- TmCalculator:::get_table("DNA_NN_SantaLucia_2004")
tbl <- rbind(tbl, "MG/CG" = c(-9.1, -24.0))
# Optional attributes. "reference" names the built-in whose key set must be
# present, which matters for RNA and hybrid tables because the default
# reference is a DNA/DNA set. "salt_mM" marks the table as fitted at a
# stated sodium concentration, so that it suppresses the salt correction at
# that concentration exactly as the built-in condition-specific sets do.
attr(tbl, "reference") <- "DNA_NN_SantaLucia_2004"
out_user <- tm_nn(seqs, nn_table = tbl, Na = 50)
out_user$options[["Thermodynamic NN values"]]
# "user-supplied (reference: DNA_NN_SantaLucia_2004)"
# Passing a built-in table back in through this route changes nothing: the
# supplied table is reordered to the reference key order before use, so row
# order carries no information.
identical(tm_nn(seqs, nn_table = "DNA_NN_SantaLucia_2004")$gr$Tm,
tm_nn(seqs,
nn_table = TmCalculator:::get_table("DNA_NN_SantaLucia_2004")
)$gr$Tm)
# A table missing a key is refused rather than tolerated. The compiled core
# resolves each stack by name, so an absent key would contribute zero
# enthalpy and entropy to every sequence containing that step, silently.
try(tm_nn(seqs, nn_table = tbl[setdiff(rownames(tbl), "AA/TT"), ]))
out_ls$options[["Parameter set fitted at [Na+] (mM)"]]
Run the code above in your browser using DataLab