Low-level thermodynamic analysis

primer3.thermoanalysis

Contains Cython functions and classes that enable repeated thermodynamic calculations using common calculation parameters.

The parameters included in this module map to the ntthal binary (thal.c/h source) in the primer3 library and ARE NOT covered in the primer design documentation provided with primer3. Please see class and method docstrings in primer3-py for parameter explanations.

Calculations are performed under the following paradigm:

Instantiate ThermoAnalysis object with appropriate parameters

oligo_calc = ThermoAnalysis(mv_conc=50, dv_conc=0.2)

Use the object instance for subsequent calculations

for primer in primer_list:
    print(oligo_calc.calc_tm(primer))  # Print the melting temp

(optional) You can update an individual parameter at any time

oligo_calc.mv_conc = 80  # Increase the monovalent ion conc to 80 mM

class primer3.thermoanalysis.ThermoAnalysis

Subclass of _ThermoAnalysis to enable singleton behavior

As of v1.2.0 no longer a Singleton as thread-safety exists

calcEndStability(seq1, seq2)

Deprecated since version 1.0.0.: Choose calc_end_stability() instead

Calculate the 3’ end stability of DNA sequence seq1 against DNA sequence seq2

Parameters:

seq1 (Union[str, bytes]) – sequence string 1
seq2 (Union[str, bytes]) – sequence string 2

Returns:

class`ThermoResult`

Return type:

Computed end stability

calcHairpin(seq1, output_structure=False)

Deprecated since version 1.0.0.: Choose calc_hairpin() instead

Calculate the hairpin formation thermodynamics of a DNA sequence, seq1

Parameters:

seq1 (Union[str, bytes]) – (str | bytes) sequence string 1
output_structure (bool) – If True, build output structure.

Return type:

ThermoResult

Returns:

Computed hairpin ThermoResult

calcHeterodimer(seq1, seq2, output_structure=False)

Deprecated since version 1.0.0.: Choose calc_heterodimer() instead

Calculate the heterodimer formation thermodynamics of two DNA sequences, seq1 and seq2

Parameters:

seq1 (Union[str, bytes]) – (str | bytes) sequence string 1
seq2 (Union[str, bytes]) – (str | bytes) sequence string 2
output_structure (bool) – If True, build output structure.

Returns:

class`ThermoResult`

Return type:

Computed heterodimer

calcHomodimer(seq1, output_structure=False)

Deprecated since version 1.0.0.: Choose calc_homodimer() instead

Calculate the homodimer formation thermodynamics of a DNA sequence, seq1

Parameters:

seq1 (Union[str, bytes]) – (str | bytes) sequence string 1
output_structure (bool) – If True, build output structure.

Return type:

ThermoResult

Returns:

Computed homodimer ThermoResult

calcTm(seq1)

Deprecated since version 1.0.0.: Choose calc_tm() instead

Calculate the melting temperature (Tm) of a DNA sequence (deg. C).

Parameters:: seq1 (Union[str, bytes]) – (str | bytes) sequence string 1
Return type:: float
Returns:: floating point Tm result

calc_end_stability(seq1, seq2)

Calculate the 3’ end stability of DNA sequence seq1 against DNA sequence seq2

Parameters:

seq1 (Union[str, bytes]) – sequence string 1
seq2 (Union[str, bytes]) – sequence string 2

Return type:

ThermoResult

Returns:

Computed end stability ThermoResult

calc_hairpin(seq1, output_structure=False)

Calculate the hairpin formation thermodynamics of a DNA sequence, seq1

Parameters:

seq1 – (str | bytes) sequence string 1
output_structure – If True, build output structure.

Returns:

Computed hairpin ThermoResult

calc_heterodimer(seq1, seq2, output_structure=False)

Calculate the heterodimer formation thermodynamics of two DNA sequences, seq1 and seq2

Parameters:

seq1 – (str | bytes) sequence string 1
seq2 – (str | bytes) sequence string 2
output_structure – If True, build output structure.

Returns:

Computed heterodimer ThermoResult

calc_homodimer(seq1, output_structure=False)

Calculate the homodimer formation thermodynamics of a DNA sequence, seq1

Parameters:

seq1 – (str | bytes) sequence string 1
output_structure – If True, build output structure.

Returns:

Computed homodimer ThermoResult

calc_tm(seq1)

Calculate the melting temperature (Tm) of a DNA sequence (deg. C).

Parameters:: seq1 (Union[str, bytes]) – (str | bytes) sequence string 1
Return type:: float
Returns:: floating point Tm result

dna_conc: Concentration of DNA oligos (nM)

dntp_conc: Concentration of dNTPs (mM)

dv_conc: Concentration of divalent cations (mM)

max_loop: Maximum hairpin loop size (bp)

mispriming_check(putative_seq, sequences, tm_threshold)

Calculate the heterodimer formation thermodynamics of a DNA sequence, putative_seq with a list of sequences relative to a melting temperature threshold

Parameters:

putative_seq – (str | bytes) sequence to check
sequences – (Iterable[str | bytes]) Iterable of sequence strings to check against
tm_threshold – melting temperature threshold

Returns:

Tuple[bool, int, float] of form::: is_offtarget (bool), max_offtarget_seq_idx (int), max_offtarget_tm (double)

mv_conc: Concentration of monovalent cations (mM)

run_design(global_args, seq_args, misprime_lib=None, mishyb_lib=None)

Wraps the primer design functionality of Primer3.

New in version 2.0.0: List versions of PRIMER_{PAIR, LEFT, RIGHT, INTERNAL} are added to the design output dictionary keys as a convenience. Original per item PRIMER_ keys are retained as well for compatibility.

Parameters:

seq_args (Optional[Dict[str, Any]]) – Primer3 sequence/design args as per Primer3 docs
global_args (Dict[str, Any]) – Primer3 global args as per Primer3 docs
misprime_lib (Optional[Dict[str, Any]]) – Sequence name: sequence dictionary for mispriming checks.
mishyb_lib (Optional[Dict[str, Any]]) – Sequence name: sequence dictionary for mishybridization checks.

Return type:

Dict[str, Any]

Returns:

primer3 key value results dictionary

salt_correction_method: Method used for salt corrections applied to melting temperature calculations. May be provided as a string (see salt_correction_methods_dict) or the respective integer representation.

set_thermo_args(mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, dmso_conc=0.0, dmso_fact=0.6, formamide_conc=0.8, annealing_temp_c=-10.0, temp_c=37.0, max_nn_length=60, max_loop=30, tm_method='santalucia', salt_corrections_method='santalucia', **kwargs)

Set parameters in global _ThermoAnalysis instance

Parameters:

mv_conc (Union[float, int]) – Monovalent cation conc. (mM)
dv_conc (Union[float, int]) – Divalent cation conc. (mM)
dntp_conc (Union[float, int]) – dNTP conc. (mM)
dna_conc (Union[float, int]) – DNA conc. (nM)
dmso_conc (float) – Concentration of DMSO (%)
dmso_fact (float) – DMSO correction factor, default 0.6
formamide_conc (float) – Concentration of formamide (mol/l)
annealing_temp_c (float) – Actual annealing temperature of the PCR reaction in (C)
temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)
max_nn_length (int) – Maximum length for nearest-neighbor calcs
tm_method (str) – Tm calculation method (breslauer or santalucia)
salt_corrections_method (str) – Salt correction method (schildkraut, owczarzy, santalucia)

temp_c: Simulation temperature (deg. C)

tm_method: Method used to calculate melting temperatures. May be provided as a string (see tm_methods_dict) or the respective integer representation.

todict()

Return type:: Dict[str, Any]
Returns:: dictionary form of the _ThermoAnalysis instance

class primer3.thermoanalysis.ThermoResult

Class that wraps the thal_results struct from libprimer3 to expose tm, dg, dh, and ds values that result from a calc_hairpin(), calc_homodimer(), calc_heterodimer(), or calc_end_stability() calculation.

ascii_structure_lines

ASCII structure representation split into individual lines

e.g.:

[
    'SEQ             -    T CCT-   A   TTGCTTTGAAACAATTCACCATGCAGA',
    'SEQ          TGC GATG G    GCT TGC                           ',
    'STR          ACG CTAC C    CGA ACG                           ',
    'STR    AACCTT   T    T TTAT   G   TAGGCGAGCCACCAGCGGCATAGTAA-',
]

check_exc()

Check the .msg attribute of the internal thalres struct and raise a RuntimeError exception if it is not an empty string. Otherwise, return a reference to the current object.

Raises:: RuntimeError – Message of internal C error
Return type:: ThermoResult

dg: delta G (Gibbs free energy) of the structure (cal/mol)

dh: delta H (entropy) of the structure (cal/mol)

ds: delta S (enthalpy) of the structure (cal/K*mol)

structure_found: Whether or not a structure (hairpin, dimer, etc) was found as a result of the calculation.

tm: Melting temperature of the structure in deg. C

todict(pts=None)

Parameters:: pts – precision to round floats to
Return type:: Dict[str, Any]
Returns:: dictionary form of the ThermoResult