app/kb/registry/tm.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/components/procedure-primers.tsx, app/kb/registry/catalog.mjs, app/kb/registry/primer.mjs.

Source

1// A primer's melting temperature, computed from its sequence and never typed (a computable value is computed). The
2// method and the conditions are stated on every page that shows a Tm, from the constants below, so a reader knows what
3// the number means and a change of condition changes every page at once.
4//
5// METHOD. The unified nearest-neighbour model of SantaLucia (1998), Proc. Natl. Acad. Sci. USA 95:1460-1465, doi
6// 10.1073/pnas.95.4.1460: the duplex's enthalpy and entropy are the sums of its dinucleotide steps plus an initiation
7// term for each end, the entropy is corrected for the monovalent salt, and
8//
9//   Tm = 1000 x dH / (dS + R x ln(C)) - 273.15
10//
11// with dH in kcal/mol, dS in cal/(K x mol), R = 1.987 cal/(K x mol) and C the primer concentration. C is the primer
12// concentration itself, not the total strand concentration over four, because in a PCR the primer is in large excess
13// over the template (for strands at unequal concentration the term is C(excess) minus half of C(limiting), which is C when
14// the template is far below the primer). A self-complementary primer also takes the symmetry term.
15//
16// CONDITIONS. 50 mM monovalent cation and 0.5 uM primer, with the template taken as far below the primer. They are the
17// usual reporting defaults, not the conditions of any one reaction buffer (a master mix's own salt and Mg2+ shift the
18// working Tm), so the figure is for comparing primers with each other. The page says so.
19//
20// A sequence with an ambiguity code or any base but A, C, G and T has no single Tm, so it has none here: null, never a
21// guess. test/registry-tm.test.mjs holds this to Biopython's Bio.SeqUtils.MeltingTemp.Tm_NN (DNA_NN3, which carries the
22// SantaLucia 1998 table, saltcorr 5, the template taken as zero).
23
24/** The conditions every Tm on the site is computed under, stored once. */
25export const TM_CONDITIONS = Object.freeze({
26  /** Monovalent cation, mM. */
27  sodiumMM: 50,
28  /** Primer, nM. */
29  primerNM: 500,
30  method: "SantaLucia (1998) unified nearest-neighbour model",
31  citation: "SantaLucia J Jr (1998), Proc Natl Acad Sci USA 95:1460-1465",
32  doi: "10.1073/pnas.95.4.1460",
33});
34
35/** The shortest oligo the model is applied to; a Tm for fewer bases is not meaningful as a primer's. */
36export const TM_MIN_LENGTH = 10;
37
38const R = 1.987;
39
40/** dH (kcal/mol) and dS (cal/(K x mol)) of each dinucleotide step, 5' to 3', SantaLucia 1998 Table 1. */
41const STEP = /** @type {Record<string, [number, number]>} */ ({
42  AA: [-7.9, -22.2],
43  TT: [-7.9, -22.2],
44  AT: [-7.2, -20.4],
45  TA: [-7.2, -21.3],
46  CA: [-8.5, -22.7],
47  TG: [-8.5, -22.7],
48  GT: [-8.4, -22.4],
49  AC: [-8.4, -22.4],
50  CT: [-7.8, -21.0],
51  AG: [-7.8, -21.0],
52  GA: [-8.2, -22.2],
53  TC: [-8.2, -22.2],
54  CG: [-10.6, -27.2],
55  GC: [-9.8, -24.4],
56  GG: [-8.0, -19.9],
57  CC: [-8.0, -19.9],
58});
59/** Initiation at a terminal G-C pair and at a terminal A-T pair, added once per end. */
60const INIT_GC = /** @type {[number, number]} */ ([0.1, -2.8]);
61const INIT_AT = /** @type {[number, number]} */ ([2.3, 4.1]);
62/** The symmetry correction for a self-complementary sequence (entropy only). */
63const SYMMETRY_DS = -1.4;
64
65const COMPLEMENT = /** @type {Record<string, string>} */ ({ A: "T", C: "G", G: "C", T: "A" });
66
67/** @param {string} sequence */
68function reverseComplement(sequence) {
69  return [...sequence].reverse().map((base) => COMPLEMENT[base]).join("");
70}
71
72/**
73 * The Tm in degrees Celsius, unrounded, or null when the sequence is not an unambiguous DNA oligo of at least
74 * TM_MIN_LENGTH bases.
75 *
76 * @param {string} sequence 5' to 3', upper case
77 * @returns {number | null}
78 */
79export function primerTm(sequence) {
80  if (!/^[ACGT]+$/.test(sequence) || sequence.length < TM_MIN_LENGTH) return null;
81  let dH = 0;
82  let dS = 0;
83  for (let i = 0; i < sequence.length - 1; i += 1) {
84    const [h, s] = /** @type {[number, number]} */ (STEP[sequence.slice(i, i + 2)]);
85    dH += h;
86    dS += s;
87  }
88  for (const end of [sequence[0], sequence[sequence.length - 1]]) {
89    const [h, s] = end === "G" || end === "C" ? INIT_GC : INIT_AT;
90    dH += h;
91    dS += s;
92  }
93  const selfComplementary = sequence === reverseComplement(sequence);
94  if (selfComplementary) dS += SYMMETRY_DS;
95  // The salt correction of SantaLucia (1998) eq. 8, applied to the entropy: 0.368 per phosphate (N - 1) x ln [Na+].
96  dS += 0.368 * (sequence.length - 1) * Math.log(TM_CONDITIONS.sodiumMM / 1000);
97  const concentration = TM_CONDITIONS.primerNM * 1e-9;
98  return (1000 * dH) / (dS + R * Math.log(concentration)) - 273.15;
99}
100
101/** The Tm to one decimal, or null where there is none. @param {string} sequence */
102export function primerTmRounded(sequence) {
103  const tm = primerTm(sequence);
104  return tm === null ? null : Math.round(tm * 10) / 10;
105}
106
107/** NEB’s Tm calculator, which gives the annealing temperature for a particular polymerase. */
108export const NEB_TM_CALCULATOR = Object.freeze({ url: "https://tmcalculator.neb.com/", name: "NEB Tm Calculator" });
109
110/**
111 * The sentence every page that shows a Tm carries: what the number is (an estimate, for comparing primers), what was
112 * computed and under what conditions, from the one set of constants, so no page restates a number it could be wrong about.
113 * It never calls the figure an annealing temperature; `annealingSentence` says where that comes from.
114 */
115export function tmStatement() {
116  const { sodiumMM, primerNM, method, citation } = TM_CONDITIONS;
117  return (
118    `The melting temperature (Tm) is an estimate for comparing primers with each other, computed from the sequence with the ${method} ` +
119    `(${citation}) at ${sodiumMM} mM monovalent cation and ${primerNM / 1000} µM primer. These are standard reporting ` +
120    `conditions, not those of any one reaction buffer. A sequence with an ambiguity code has no single Tm and shows none.`
121  );
122}
123
124/** Where the annealing temperature comes from: not from the Tm above. Plain text, with the calculator named. */
125export function annealingSentence() {
126  return `The Tm estimate is not an annealing temperature. For the annealing temperature of a particular polymerase, use the ${NEB_TM_CALCULATOR.name} (${NEB_TM_CALCULATOR.url}).`;
127}