Primary analysis and design API

primer3.bindings

This module provides a simple API for the Primer3 primer design / thermodynamic calculations library.

These are direct bindings to an optimized version of the Primer3 C library, as opposed to the more commonly used subprocess-based wrappers (we provide a set of wrappers for comparison / testing purposes as well).

Note that this module effectively abstracts the C API / Cython bindings for the primer design and thermodynamic analysis functionality of Primer3. This is done primarly to provide a clean, consistent interface. For applications with stringent performance requirments, you should consider using the C API and/or Cython modules directly. See the docs for more details.

primer3.bindings.calcEndStability(seq1, seq2, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30)[source]

Deprecated. Choose calc_end_stability() function instead

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

Note that at least one of the two sequences must by <60 bp in length. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq1 (Union[str, bytes]) – DNA sequence to analyze for 3’ end hybridization against the target sequence

  • seq2 (Union[str, bytes]) – Target DNA sequence to analyze for seq1 3’ end hybridization

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int) – Maximum size of loops in the structure

Return type:

ThermoResult

Returns:

A ThermoResult object with thermodynamic characteristics of the 3’ hybridization interaction.

Raises:

RuntimeError –

primer3.bindings.calcHairpin(seq, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Deprecated since version 1.0.0.: Choose calc_hairpin() function instead

Calculate the hairpin formation thermodynamics of a DNA sequence.

Note that the maximum length of `seq` is 60 bp. This is a cap suggested by the Primer3 team as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq (Union[str, bytes]) – DNA sequence to analyze for hairpin formation

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int, optional) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Returns:

A ThermoResult object with thermodynamic characteristics of the hairpin formation.

Raises:

RuntimeError –

primer3.bindings.calcHairpinTm(*args, **kwargs)[source]

Deprecated since version 1.0.0.: Choose calc_hairpin_tm() function instead

Return type:

float

primer3.bindings.calcHeterodimer(seq1, seq2, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Deprecated since version 1.0.0.: Choose calc_heterodimer() function instead

Calculate the heterodimerization thermodynamics of two DNA sequences.

Note that at least one of the two sequences must by <60 bp in length. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq1 (Union[str, bytes]) – First DNA sequence to analyze for heterodimer formation

  • seq2 (Union[str, bytes]) – Second DNA sequence to analyze for heterodimer formation

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Return type:

ThermoResult

Returns:

A ThermoResult object with thermodynamic characteristics of the heterodimer interaction.

Raises:

RuntimeError –

primer3.bindings.calcHeterodimerTm(*args, **kwargs)[source]

Deprecated since version 1.0.0.: Choose calc_heterodimer_tm() function

instead

Return type:

float

primer3.bindings.calcHomodimer(seq, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Deprecated since version 1.0.0.: Choose calc_homodimer() function instead

Calculate the homodimerization thermodynamics of a DNA sequence.

Note that the maximum length of ``seq`` is 60 bp. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq (Union[str, bytes]) – DNA sequence to analyze for homodimer formation calculations

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Returns:

A ThermoResult object with thermodynamic characteristics of the homodimer interaction.

Raises:

RuntimeError –

primer3.bindings.calcHomodimerTm(*args, **kwargs)[source]

Deprecated since version 1.0.0.: Choose calc_homodimer_tm() function instead

Return type:

float

primer3.bindings.calcTm(seq, 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, max_nn_length=60, tm_method='santalucia', salt_corrections_method='santalucia')[source]

Deprecated since version 1.0.0.: Choose calc_tm() function instead

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

Note that NN thermodynamics will be used to calculate the Tm of sequences up to 60 bp in length, after which point the following formula will be used:

Tm = 81.5 + 16.6(log10([mv_conc])) + 0.41(%GC) - 600/length
Parameters:

  • seq (Union[str, bytes]) – DNA sequence

  • 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 – 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)

Return type:

float

Returns:

The melting temperature in degrees Celsius (float).

primer3.bindings.calc_end_stability(seq1, seq2, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30)[source]
Return type:

ThermoResult

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

sequence seq2.

Note that at least one of the two sequences must by <60 bp in length. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see

primer3/src/libnano/thal.h:59).

Args:
seq1: DNA sequence to analyze for 3’ end hybridization against the

target sequence

seq2: Target DNA sequence to analyze for seq1 3’ end hybridization mv_conc: Monovalent cation conc. (mM) dv_conc: Divalent cation conc. (mM) dntp_conc: dNTP conc. (mM) dna_conc: DNA conc. (nM) temp_c: Simulation temperature for dG (Celsius) max_loop: Maximum size of loops in the structure

Returns:

A ThermoResult object with thermodynamic characteristics of the 3’ hybridization interaction.

Raises:

RuntimeError

primer3.bindings.calc_hairpin(seq, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Calculate the hairpin formation thermodynamics of a DNA sequence.

Note that the maximum length of ``seq`` is 60 bp. This is a cap suggested by the Primer3 team as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq (Union[str, bytes]) – DNA sequence to analyze for hairpin formation

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int, optional) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Returns:

A ThermoResult object with thermodynamic characteristics of the hairpin formation.

Raises:

RuntimeError –

primer3.bindings.calc_heterodimer(seq1, seq2, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Calculate the heterodimerization thermodynamics of two DNA sequences.

Note that at least one of the two sequences must by <60 bp in length. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq1 (Union[str, bytes]) – First DNA sequence to analyze for heterodimer formation

  • seq2 (Union[str, bytes]) – Second DNA sequence to analyze for heterodimer formation

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Return type:

ThermoResult

Returns:

A ThermoResult object with thermodynamic characteristics of the heterodimer interaction.

Raises:

RuntimeError –

primer3.bindings.calc_homodimer(seq, mv_conc=50.0, dv_conc=1.5, dntp_conc=0.6, dna_conc=50.0, temp_c=37.0, max_loop=30, output_structure=False)[source]

Calculate the homodimerization thermodynamics of a DNA sequence.

Note that the maximum length of ``seq`` is 60 bp. This is a cap imposed by Primer3 as the longest reasonable sequence length for which a two-state NN model produces reliable results (see primer3/src/libnano/thal.h:59).

Parameters:

  • seq (Union[str, bytes]) – DNA sequence to analyze for homodimer formation calculations

  • 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)

  • temp_c (Union[float, int]) – Simulation temperature for dG (Celsius)

  • max_loop (int) – Maximum size of loops in the structure

  • output_structure (bool) – If True, the ASCII dimer structure is saved

Returns:

A ThermoResult object with thermodynamic characteristics of the homodimer interaction.

Raises:

RuntimeError –

primer3.bindings.calc_tm(seq, 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, max_nn_length=60, tm_method='santalucia', salt_corrections_method='santalucia')[source]

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

Note that NN thermodynamics will be used to calculate the Tm of sequences up to 60 bp in length, after which point the following formula will be used:

Tm = 81.5 + 16.6(log10([mv_conc])) + 0.41(%GC) - 600/length
Parameters:

  • seq (Union[str, bytes]) – DNA sequence

  • 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 – 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)

Return type:

float

Returns:

The melting temperature in degrees Celsius (float).

primer3.bindings.designPrimers(seq_args, global_args, misprime_lib=None, mishyb_lib=None)[source]

Deprecated since version 1.0.0: Choose design_primers() function instead

Run the Primer3 design process.

Parameters:

  • seq_args (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:

A dictionary of Primer3 results (should be identical to the expected BoulderIO output from primer3_main)

primer3.bindings.design_primers(seq_args, global_args, misprime_lib=None, mishyb_lib=None)[source]

Run the Primer3 design process. This is a wrapper around _ThermoAnalysis.run_design().

Parameters:

  • seq_args (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:

A dictionary of Primer3 results (should be identical to the expected BoulderIO output from primer3_main)