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, dv_conc=0, dntp_conc=0.8, dna_conc=50, temp_c=37, max_loop=30)[source]

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:50).

Parameters:
  • seq1 (str) – DNA sequence to analyze for 3’ end hybridization against the target sequence
  • seq2 (str) – Target DNA sequence to analyze for seq1 3’ end hybridization
  • mv_conc (float/int, optional) – Monovalent cation conc. (mM)
  • dv_conc (float/int, optional) – Divalent cation conc. (mM)
  • dntp_conc (float/int, optional) – dNTP conc. (mM)
  • dna_conc (float/int, optional) – DNA conc. (nM)
  • temp_c (int, optional) – Simulation temperature for dG (C)
  • max_loop (int, optional) – Maximum size of loops in the structure
Returns:

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

Raises:

RuntimeError

primer3.bindings.calcHairpin(seq, mv_conc=50.0, dv_conc=0.0, dntp_conc=0.8, dna_conc=50.0, temp_c=37, max_loop=30)[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:50).

Parameters:
  • seq (str) – DNA sequence to analyze for hairpin formation
  • mv_conc (float/int, optional) – Monovalent cation conc. (mM)
  • dv_conc (float/int, optional) – Divalent cation conc. (mM)
  • dntp_conc (float/int, optional) – dNTP conc. (mM)
  • dna_conc (float/int, optional) – DNA conc. (nM)
  • temp_c (int, optional) – Simulation temperature for dG (Celsius)
  • max_loop (int, optional) – Maximum size of loops in the structure
Returns:

A ThermoResult object with thermodynamic characteristics of the hairpin formation.

Raises:

RuntimeError

primer3.bindings.calcHeterodimer(seq1, seq2, mv_conc=50, dv_conc=0, dntp_conc=0.8, dna_conc=50, temp_c=37, max_loop=30)[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:50).

Parameters:
  • seq1 (str) – First DNA sequence to analyze for heterodimer formation
  • seq2 (str) – Second DNA sequence to analyze for heterodimer formation
  • mv_conc (float/int) – Monovalent cation conc. (mM)
  • dv_conc (float/int) – Divalent cation conc. (mM)
  • dntp_conc (float/int) – dNTP conc. (mM)
  • dna_conc (float/int) – DNA conc. (nM)
  • temp_c (int) – Simulation temperature for dG (Celsius)
  • max_loop (int) – Maximum size of loops in the structure
Returns:

A ThermoResult object with thermodynamic characteristics of the heterodimer interaction.

Raises:

RuntimeError

primer3.bindings.calcHomodimer(seq, mv_conc=50, dv_conc=0, dntp_conc=0.8, dna_conc=50, temp_c=37, max_loop=30)[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:50).

Parameters:
  • seq (str) – DNA sequence to analyze for homodimer formation calculations
  • mv_conc (float/int, optional) – Monovalent cation conc. (mM)
  • dv_conc (float/int, optional) – Divalent cation conc. (mM)
  • dntp_conc (float/int, optional) – dNTP conc. (mM)
  • dna_conc (float/int, optional) – DNA conc. (nM)
  • temp_c (int, optional) – Simulation temperature for dG (C)
  • max_loop (int, optional) – Maximum size of loops in the structure
Returns:

A ThermoResult object with thermodynamic characteristics of the homodimer interaction.

Raises:

RuntimeError

primer3.bindings.calcTm(seq, mv_conc=50, dv_conc=0, dntp_conc=0.8, dna_conc=50, 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 (str) – DNA sequence
  • mv_conc (float/int, optional) – Monovalent cation conc. (mM)
  • dv_conc (float/int, optional) – Divalent cation conc. (mM)
  • dntp_conc (float/int, optional) – dNTP conc. (mM)
  • dna_conc (float/int, optional) – DNA conc. (nM)
  • max_nn_length (int, optional) – Maximum length for nearest-neighbor calcs
  • tm_method (str, optional) – Tm calculation method (breslauer or santalucia)
  • salt_corrections_method (str, optional) – Salt correction method (schildkraut, owczarzy, santalucia)
Returns:

The melting temperature in degrees Celsius (float).

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

Run the Primer3 design process.

If the global args have been previously set (either by a pervious designPrimers call or by a setGlobals call), designPrimers may be called with seqArgs alone (as a means of optimization).

Parameters:
  • seq_args (dict) – Primer3 sequence/design args as per Primer3 docs
  • global_args (dict, optional) – Primer3 global args as per Primer3 docs
  • misprime_lib (dict, optional) – Sequence name: sequence dictionary for mispriming checks.
  • mishyb_lib (dict, optional) – Sequence name: sequence dictionary for mishybridization checks.
Returns:

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

primer3.bindings.runP3Design(debug=False)[source]

Start the Primer3 design process, return a dict of the Primer3 output.

The global parameters and seq args must have been previously set prior to this call (raises IOError).

Parameters:debug (bool, optional) – If True, prints the received design params to stderr for debugging purposes
Returns:A dictionary of Primer3 results (should be identical to the expected BoulderIO output from primer3_main)
primer3.bindings.setP3Globals(global_args, misprime_lib=None, mishyb_lib=None)[source]

Set the Primer3 global args and misprime/mishyb libraries.

Parameters:
  • global_args (dict) – Primer3 global parameters as per Primer3 docs
  • misprime_lib (dict, optional) – <Sequence name: sequence> dict for mispriming checks.
  • mishyb_lib (dict, optional) – <Sequence name: sequence> dict for mishybridization checks.
Returns:

None

primer3.bindings.setP3SeqArgs(seq_args)[source]

Set the Primer3 sequence / design arguments.

Parameters:seq_args (dict) – Primer3 seq/design args as per Primer3 docs
Returns:None