@teselagen/sequence-utils 0.3.37 → 0.3.38-beta.2

package/src/calculateNebTm.ts

@@ -0,0 +1,132 @@
+import getComplementSequenceString from "./getComplementSequenceString";
+import calculatePercentGc from "./calculatePercentGC";
+
+// sources of formulas:
+// - https://tmcalculator.neb.com/#!/help
+// - Tm calculation: SantaLucia (1998) PNAS 95:1460-5
+// - salt correction (for monovalent cations): Owczarzy (2004) Biochem 43:3537-54
+
+// primer concentration & monovalent cation concentration in M
+
+interface NebTmOptions {
+  monovalentCationConc?: number;
+  primerConc?: number;
+}
+
+export default function calculateNebTm(
+  sequence: string,
+  { monovalentCationConc = 0.05, primerConc = 0.0000005 }: NebTmOptions = {}
+): number | string {
+  try {
+    const checkForDegenerateBases = /[^atgc]/i.test(sequence);
+    if (checkForDegenerateBases) {
+      throw new Error(
+        `Degenerate bases prohibited in Tm calculation of sequence ${sequence}`
+      );
+    }
+    const seq = sequence.toUpperCase().split("");
+    // enthalpy, entropy
+    let h = 0;
+    let s = 0;
+    // adjustments for helix initiation
+    let hi = 0;
+    let si = 0;
+    // R = universal gas constant with units of cal/(K*mol)
+    const r = 1.987;
+    // to convert the units of Tm from kelvin to celsius and vice versa
+    const kelvinToCelsius = -273.15;
+    const celsiusToKelvin = 273.15;
+    // to convert the units of enthalpy from kilocal/mol to cal/mol
+    const kilocalToCal = 1000;
+    const sequenceToEnthalpyMap: Record<string, number> = {
+      "AA/TT": -7.9,
+      "AT/TA": -7.2,
+      "TA/AT": -7.2,
+      "CA/GT": -8.5,
+      "GT/CA": -8.4,
+      "CT/GA": -7.8,
+      "GA/CT": -8.2,
+      "CG/GC": -10.6,
+      "GC/CG": -9.8,
+      "GG/CC": -8.0,
+      "TT/AA": -7.9,
+      "TG/AC": -8.5,
+      "AC/TG": -8.4,
+      "AG/TC": -7.8,
+      "TC/AG": -8.2,
+      "CC/GG": -8.0,
+      initiationWithTerminalGC: 0.1,
+      initiationWithTerminalAT: 2.3
+    };
+    const sequenceToEntropyMap: Record<string, number> = {
+      "AA/TT": -22.2,
+      "AT/TA": -20.4,
+      "TA/AT": -21.3,
+      "CA/GT": -22.7,
+      "GT/CA": -22.4,
+      "CT/GA": -21.0,
+      "GA/CT": -22.2,
+      "CG/GC": -27.2,
+      "GC/CG": -24.4,
+      "GG/CC": -19.9,
+      "TT/AA": -22.2,
+      "TG/AC": -22.7,
+      "AC/TG": -22.4,
+      "AG/TC": -21.0,
+      "TC/AG": -22.2,
+      "CC/GG": -19.9,
+      initiationWithTerminalGC: -2.8,
+      initiationWithTerminalAT: 4.1
+    };
+    for (let i = 0; i < seq.length; i++) {
+      if (i === 0 || i === seq.length - 1) {
+        // first or last nucleotide
+        if (seq[i] === "G" || seq[i] === "C") {
+          hi += sequenceToEnthalpyMap["initiationWithTerminalGC"];
+          si += sequenceToEntropyMap["initiationWithTerminalGC"];
+        } else if (seq[i] === "A" || seq[i] === "T") {
+          hi += sequenceToEnthalpyMap["initiationWithTerminalAT"];
+          si += sequenceToEntropyMap["initiationWithTerminalAT"];
+        }
+      }
+      if (i < seq.length - 1) {
+        const dimer = seq[i] + seq[i + 1];
+        const complement = getComplementSequenceString(dimer).toUpperCase();
+        const dimerDuplex = `${dimer}/${complement}`;
+        if (
+          !sequenceToEnthalpyMap[dimerDuplex] ||
+          !sequenceToEntropyMap[dimerDuplex]
+        ) {
+          throw new Error(
+            `Could not find value for ${dimerDuplex} of sequence ${sequence}`
+          );
+        }
+        h += sequenceToEnthalpyMap[dimerDuplex];
+        s += sequenceToEntropyMap[dimerDuplex];
+      }
+    }
+    // this calculated Tm assumes 1 M monovalent cation concentration
+    const deltaH = h + hi;
+    const deltaS = s + si;
+    const numerator = deltaH * kilocalToCal;
+    const denominator = deltaS + r * Math.log(primerConc);
+    const meltingTemp = numerator / denominator + kelvinToCelsius;
+    if (monovalentCationConc) {
+      // adjusting Tm for actual monovalent cation concentration
+      const lnOfMonoConc = Math.log(monovalentCationConc);
+      const gcContent = calculatePercentGc(sequence) / 100;
+      const part = 4.29 * gcContent - 3.95;
+      const saltCorrection =
+        part * Math.pow(10, -5) * lnOfMonoConc +
+        Math.pow(9.4, -6) * Math.pow(lnOfMonoConc, 2);
+      const adjustedMeltingTemp =
+        1 / (1 / (meltingTemp + celsiusToKelvin) + saltCorrection) +
+        kelvinToCelsius;
+      return adjustedMeltingTemp;
+    } else {
+      return meltingTemp;
+    }
+  } catch (err) {
+    return `Error calculating Tm for sequence ${sequence}: ${err}`;
+  }
+}

package/src/calculatePercentGC.ts

@@ -0,0 +1,3 @@
+export default function calculatePercentGC(bps: string): number {
+  return ((bps.match(/[cg]/gi) || []).length / bps.length) * 100 || 0;
+}

package/src/calculateSantaLuciaTm.ts

@@ -0,0 +1,184 @@
+/**
+ * Primer3 Melting Temperature Calculator
+ *
+ * Implements the melting temperature calculation algorithm from Primer3
+ * based on the documentation at https://primer3.ut.ee/primer3web_help.htm
+ *
+ * Uses SantaLucia (1998) nearest-neighbor thermodynamics method with
+ * fixed Primer3 custom parameters:
+ * - Formula: SantaLucia (1998)
+ * - Salt correction: SantaLucia (1998)
+ * - Monovalent salt: 50.0 mM
+ * - Divalent salt: 1.5 mM
+ * - dNTP concentration: 0.6 mM
+ * - DNA concentration: 50.0 nM
+ *
+ * References:
+ * - SantaLucia JR (1998) "A unified view of polymer, dumbbell and
+ *   oligonucleotide DNA nearest-neighbor thermodynamics",
+ *   Proc Natl Acad Sci 95:1460-65
+ */
+
+export interface SantaLuciaParams {
+  dH: number;
+  dS: number;
+}
+
+// Primer3 custom parameters (fixed)
+const PRIMER3_PARAMS = {
+  saltMonovalent: 50.0, // mM
+  saltDivalent: 1.5, // mM
+  dntpConc: 0.6, // mM
+  dnaConc: 50.0, // nM
+  R: 1.987 // Gas constant (cal/K·mol)
+};
+
+// SantaLucia (1998) nearest-neighbor parameters
+// dH in kcal/mol, dS in cal/K·mol
+export const SANTA_LUCIA_NN: Record<string, SantaLuciaParams> = {
+  AA: { dH: -7.9, dS: -22.2 },
+  TT: { dH: -7.9, dS: -22.2 },
+  AT: { dH: -7.2, dS: -20.4 },
+  TA: { dH: -7.2, dS: -21.3 },
+  CA: { dH: -8.5, dS: -22.7 },
+  TG: { dH: -8.5, dS: -22.7 },
+  GT: { dH: -8.4, dS: -22.4 },
+  AC: { dH: -8.4, dS: -22.4 },
+  CT: { dH: -7.8, dS: -21.0 },
+  AG: { dH: -7.8, dS: -21.0 },
+  GA: { dH: -8.2, dS: -22.2 },
+  TC: { dH: -8.2, dS: -22.2 },
+  CG: { dH: -10.6, dS: -27.2 },
+  GC: { dH: -9.8, dS: -24.4 },
+  GG: { dH: -8.0, dS: -19.9 },
+  CC: { dH: -8.0, dS: -19.9 }
+};
+
+// Initiation parameters (SantaLucia 1998)
+export const SANTA_LUCIA_INIT: Record<string, SantaLuciaParams> = {
+  GC: { dH: 0.1, dS: -2.8 }, // initiation with terminal GC
+  AT: { dH: 2.3, dS: 4.1 } // initiation with terminal AT
+};
+
+/**
+ * Calculate effective monovalent cation concentration
+ * Accounts for divalent cations (Mg2+) binding to dNTPs
+ * Formula from von Ahsen et al. (2001)
+ *
+ * @returns {number} - Effective monovalent concentration in mM
+ */
+function getEffectiveMonovalentConc(): number {
+  let effectiveMono = PRIMER3_PARAMS.saltMonovalent;
+
+  // Adjust for divalent cations
+  if (PRIMER3_PARAMS.saltDivalent > 0) {
+    const freeMg = Math.max(
+      0,
+      PRIMER3_PARAMS.saltDivalent - PRIMER3_PARAMS.dntpConc
+    );
+    effectiveMono += 120 * Math.sqrt(freeMg);
+  }
+
+  return effectiveMono;
+}
+
+/**
+ * Apply SantaLucia (1998) salt correction to entropy
+ *
+ * @param {number} deltaS - Entropy in cal/K·mol
+ * @param {number} nnPairs - Number of nearest-neighbor pairs
+ * @returns {number} - Corrected entropy in cal/K·mol
+ */
+function applySaltCorrection(deltaS: number, nnPairs: number): number {
+  const effectiveMono = getEffectiveMonovalentConc();
+  // SantaLucia (1998) salt correction
+  return deltaS + 0.368 * nnPairs * Math.log(effectiveMono / 1000);
+}
+
+/**
+ * Validate DNA sequence
+ *
+ * @param {string} sequence - DNA sequence
+ * @returns {boolean} - True if valid
+ */
+export function isValidSequence(sequence: string): boolean {
+  return /^[ATGCN]+$/.test(sequence);
+}
+
+/**
+ * Calculate melting temperature using SantaLucia (1998) method
+ *
+ * @param {string} sequence - DNA sequence (5' to 3')
+ * @returns {number} - Melting temperature in Celsius
+ * @throws {Error} Invalid sequence or too short.
+ */
+export default function calculateSantaLuciaTm(
+  sequence: string
+): number | string {
+  // Convert to uppercase and validate
+  try {
+    const seq = sequence?.toUpperCase().trim();
+
+    if (!isValidSequence(seq)) {
+      throw new Error("Invalid sequence: contains non-DNA characters");
+    }
+
+    if (seq.length < 2) {
+      throw new Error("Sequence too short: minimum length is 2 bases");
+    }
+
+    let deltaH = 0; // kcal/mol
+    let deltaS = 0; // cal/K·mol
+
+    // Calculate nearest-neighbor contributions
+    for (let i = 0; i < seq.length - 1; i++) {
+      const dinucleotide = seq.substring(i, i + 2);
+
+      // Skip if contains N
+      if (dinucleotide.includes("N")) {
+        continue;
+      }
+
+      const params = SANTA_LUCIA_NN[dinucleotide];
+      if (params) {
+        deltaH += params.dH;
+        deltaS += params.dS;
+      }
+    }
+
+    // Add initiation parameters
+    const firstBase = seq[0];
+    const lastBase = seq[seq.length - 1];
+
+    // Terminal GC or AT initiation
+    if (firstBase === "G" || firstBase === "C") {
+      deltaH += SANTA_LUCIA_INIT["GC"].dH;
+      deltaS += SANTA_LUCIA_INIT["GC"].dS;
+    } else {
+      deltaH += SANTA_LUCIA_INIT["AT"].dH;
+      deltaS += SANTA_LUCIA_INIT["AT"].dS;
+    }
+
+    if (lastBase === "G" || lastBase === "C") {
+      deltaH += SANTA_LUCIA_INIT["GC"].dH;
+      deltaS += SANTA_LUCIA_INIT["GC"].dS;
+    } else {
+      deltaH += SANTA_LUCIA_INIT["AT"].dH;
+      deltaS += SANTA_LUCIA_INIT["AT"].dS;
+    }
+
+    // Apply salt correction
+    const nnPairs = seq.length - 1;
+    deltaS = applySaltCorrection(deltaS, nnPairs);
+
+    // Calculate Tm using: Tm = deltaH / (deltaS + R * ln(C/4))
+    // where C is DNA concentration in M (convert from nM)
+    const C = PRIMER3_PARAMS.dnaConc * 1e-9; // Convert nM to M
+    const Tm = (deltaH * 1000) / (deltaS + PRIMER3_PARAMS.R * Math.log(C / 4));
+
+    // Convert from Kelvin to Celsius
+    return Tm - 273.15;
+  } catch (e) {
+    return `Error calculating Tm for sequence ${sequence}. ${e}`;
+  }
+}

package/src/calculateTm.ts

@@ -0,0 +1,242 @@
+/* eslint-disable eqeqeq */
+/**
+ * DNA melting temperature calculator.
+ * @author Nick Elsbree
+ * @author Zinovii Dmytriv (original author)
+ */
+
+interface CalculateTemperatureOptions {
+  type?: "breslauer" | "sugimoto" | "unified";
+  A?: number;
+  R?: number;
+  primerConc?: number;
+  monovalentCationConc?: number;
+}
+
+const calcTmMethods = {
+  TABLE_BRESLAUER: "breslauer" as const,
+  TABLE_SUGIMOTO: "sugimoto" as const,
+  TABLE_UNIFIED: "unified" as const,
+
+  A: -10.8, // Helix initiation for deltaS
+  R: 1.987, // Gas constant (cal/(K*mol)).
+  primerConc: 0.0000005, // Oligo concentration. 0.5uM is typical for PCR.
+  monovalentCationConc: 0.05, // Monovalent salt concentration. 50mM is typical for PCR.
+
+  /**
+   * Calculates temperature for DNA sequence using a given algorithm.
+   * sequence - The DNA sequence to use.
+   * type - Either Teselagen.bio.tools.TemperatureCalculator.TABLE_BRESLAUER, TABLE_SUGIMOTO, or TABLE_UNIFIED
+   * A - Helix initation for deltaS. Defaults to -10.8.
+   * R - The gas constant, in cal/(K*mol). Defaults to 0.5e-6M.
+   * monovalentCationConc - THe monovalent salt concentration. Defaults to 50e-3M.
+   * return - Temperature for the given sequence, in Celsius.
+   */
+  calculateTemperature: function (
+    _sequence: string,
+    {
+      type,
+      A,
+      R,
+      primerConc,
+      monovalentCationConc
+    }: CalculateTemperatureOptions = {}
+  ): number {
+    const sequence = (_sequence || "").toLowerCase();
+    if (typeof type === "undefined") {
+      // type = this.TABLE_SUGIMOTO  ;
+      // type = this.TABLE_UNIFIED;
+      type = this.TABLE_BRESLAUER;
+    } else if (
+      type !== this.TABLE_BRESLAUER &&
+      type !== this.TABLE_UNIFIED &&
+      type !== this.TABLE_SUGIMOTO
+    ) {
+      throw new Error("Invalid table type!");
+    }
+
+    /* eslint-disable no-param-reassign */
+    if (!A) {
+      A = this.A;
+    }
+    if (!R) {
+      R = this.R;
+    }
+    if (!primerConc) {
+      primerConc = this.primerConc;
+    }
+    if (!monovalentCationConc) {
+      monovalentCationConc = this.monovalentCationConc;
+    }
+    /* eslint-enable no-param-reassign */
+
+    const sequenceLength = sequence.length;
+
+    if (sequenceLength === 0) {
+      return 0;
+    }
+
+    const deltaHTable = this.getDeltaHTable(type);
+    const deltaSTable = this.getDeltaSTable(type);
+
+    if (!deltaHTable || !deltaSTable) {
+      // Should not happen if type validation passes
+      return 0;
+    }
+
+    const neighbors: number[] = []; // List goes in order: aa, at, ac, ag, tt, ta, tc, tg, cc, ca, ct, cg, gg, ga, gt, gc
+
+    neighbors.push(this.calculateReps(sequence, "aa"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "at"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ac"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ag"));
+
+    neighbors.push(this.calculateReps(sequence, "tt"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ta"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "tc"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "tg"));
+
+    neighbors.push(this.calculateReps(sequence, "cc"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ca"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ct"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "cg"));
+
+    neighbors.push(this.calculateReps(sequence, "gg"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "ga"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "gt"));
+    neighbors.push(this.calculateNumberOfOccurrences(sequence, "gc"));
+
+    let sumDeltaH = 0.0;
+    let sumDeltaS = 0.0;
+
+    for (let i = 0; i < 16; i++) {
+      // Safe access as neighbors and tables are 16-length
+      sumDeltaH = sumDeltaH + neighbors[i] * deltaHTable[i];
+      sumDeltaS = sumDeltaS + neighbors[i] * deltaSTable[i];
+    }
+
+    const temperature =
+      (-1000.0 * sumDeltaH) /
+        (A + -sumDeltaS + R * Math.log(primerConc / 4.0)) -
+      273.15 +
+      16.6 * Math.LOG10E * Math.log(monovalentCationConc);
+
+    return temperature;
+  },
+
+  /**
+   * @private
+   * Function to return deltaH table for given algorithm.
+   * @param {String} type Algorithm to get table for.
+   * @return {Number[]} deltaH table for given algorithm.
+   */
+  getDeltaHTable: function (type: string): number[] | null {
+    if (type === this.TABLE_BRESLAUER) {
+      return [
+        9.1, 8.6, 6.5, 7.8, 9.1, 6.0, 5.6, 5.8, 11.0, 5.8, 7.8, 11.9, 11.0, 5.6,
+        6.5, 11.1
+      ];
+    } else if (type === this.TABLE_SUGIMOTO) {
+      return [
+        8.0, 5.6, 6.5, 7.8, 8.0, 5.6, 5.6, 5.8, 10.9, 8.2, 6.6, 11.8, 10.9, 6.6,
+        9.4, 11.9
+      ];
+    } else if (type === this.TABLE_UNIFIED) {
+      return [
+        7.9, 7.2, 8.4, 7.8, 7.9, 7.2, 8.2, 8.5, 8.0, 8.5, 7.8, 10.6, 8.0, 8.2,
+        8.4, 9.8
+      ];
+    } else {
+      return null;
+    }
+  },
+
+  /**
+   * @private
+   * Function to return deltaS table for given algorithm.
+   * @param {String} type Algorithm to get table for.
+   * @return {Number[]} deltaS table for given algorithm.
+   */
+  getDeltaSTable: function (type: string): number[] | null {
+    if (type === this.TABLE_BRESLAUER) {
+      return [
+        24.0, 23.9, 17.3, 20.8, 24.0, 16.9, 13.5, 12.9, 26.6, 12.9, 20.8, 27.8,
+        26.6, 13.5, 17.3, 26.7
+      ];
+    } else if (type === this.TABLE_SUGIMOTO) {
+      return [
+        21.9, 15.2, 17.3, 20.8, 21.9, 15.2, 13.5, 12.9, 28.4, 25.5, 23.5, 29.0,
+        28.4, 16.4, 25.5, 29.0
+      ];
+    } else if (type === this.TABLE_UNIFIED) {
+      return [
+        22.2, 20.4, 22.4, 21.0, 22.2, 21.3, 22.2, 22.7, 19.9, 22.7, 21.0, 27.2,
+        19.9, 22.2, 22.4, 24.4
+      ];
+    } else {
+      return null;
+    }
+  },
+
+  /**
+   * @private
+   * Finds number of occurrences of target in sequence.
+   * Will find repeating sequences, meaning that
+   * calculateReps("aaa", "aa") returns 2 rather than 1.
+   * @param  {String} sequence The string to search through.
+   * @param  {String} target   The string to search for.
+   * @return {Int} Number of occurrences of target in sequence, with repeats.
+   */
+  calculateReps: function (sequence: string, target: string): number {
+    const sequenceLength = sequence.length;
+
+    if (sequenceLength === 0) {
+      return 0;
+    }
+
+    let numFound = 0;
+    let seqOffset = 0; // Search offset for finding multiple matches.
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const foundSeq = sequence.indexOf(target, seqOffset);
+
+      if (foundSeq === -1) {
+        break;
+      }
+
+      seqOffset = foundSeq + 1;
+      numFound++;
+
+      if (seqOffset > sequenceLength) {
+        break;
+      }
+    }
+
+    return numFound;
+  },
+
+  /**
+   * @private
+   * Counts number of occurrences of target in sequence, without repeating.
+   * @param  {String} sequence The string to search through.
+   * @param  {String} target   The string to search for.
+   * @return {Int} Number of occurrences of target in sequence.
+   */
+  calculateNumberOfOccurrences: function (
+    sequence: string,
+    target: string
+  ): number {
+    const sequenceLength = sequence.length;
+
+    if (sequenceLength === 0) {
+      return 0;
+    }
+
+    const numberFound = sequence.split(target).length - 1;
+
+    return numberFound;
+  }
+};
+
+export default calcTmMethods.calculateTemperature.bind(calcTmMethods);