Bio Primer Design Primer Basics

Version Compatibility

Reference examples tested with: primer3-py 2.3+.

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show primer3-py then help(primer3.design_primers) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

PCR Primer Design -- Ranked Pairs Under Local Thermodynamic Constraints

"Design primers to amplify this region" -> Search candidate primer pairs that satisfy Tm/GC/size/complementarity constraints on the supplied template and rank them by a weighted penalty -- because primer3 sees only that one template, so its top pair certifies LOCAL good behavior, not that the primers bind the target uniquely in the genome.

• Python: primer3.design_primers(seq_args, global_args) returns a flat dict of ranked pairs with per-primer Tm/GC and a pair penalty.

Scope: designing and ranking PCR primer pairs for a template under thermodynamic and positional constraints, including cloning (5' tails), genotyping (flanking), and single sequencing primers. Genome-wide off-target / in-silico PCR specificity -> primer-specificity. Dimer/hairpin/end-stability validation of chosen oligos -> primer-validation. qPCR primers and hydrolysis/beacon probes -> qpcr-primers. OUT OF SCOPE: degenerate/consensus primers for divergent targets (primer3 does not model IUPAC degeneracy -- use a dedicated consensus designer); long-range PCR amplicons over ~3-5 kb (different polymerase and primer regime); and bisulfite/methylation (MSP/BSP) primers (different rules -- avoid CpGs in the body, account for C->T strand asymmetry -- use a bisulfite-specific designer such as MethPrimer). Fetching the template -> database-access/entrez-fetch. Reverse-complement / subsequence extraction -> sequence-manipulation/seq-objects.

The Single Most Important Modern Insight -- PRIMER_PAIR_0 Is the Argmin of a Penalty the User Partly Authors, on the Only Template primer3 Sees

1. primer3 optimizes locally and is blind to the rest of the genome. It solves a constrained penalty minimization over the ONE SEQUENCE_TEMPLATE string: it scores Tm, GC, length, self-/cross-complementarity, hairpins, and 3'-end stability, then returns the lowest-penalty pairs. It never asks whether those primers also bind 50 other loci. So PRIMER_PAIR_0 means "lowest penalty under the chosen weights and bounds, on this one template" -- it is a hypothesis, not a result. The catastrophic, common error is ordering the top pair without a genome specificity pass (-> primer-specificity).
2. Tm is a prediction, not a property. primer3 computes a nearest-neighbor Tm (SantaLucia 1998 PNAS 95:1460) at a specific oligo concentration and salt; change the salt/Mg/DNA-conc inputs and the same sequence reports a different Tm. Use predicted Tm to MATCH the two primers (within ~1-2 C) and to RANK candidates, not as the literal anneal temperature. The single largest predicted-vs-bench divergence is free Mg2+ (dNTPs chelate Mg2+ roughly 1:1, so free Mg2+ ~= total Mg - total dNTP; Owczarzy 2008 Biochemistry 47:5336).
3. Bounds and weights do different jobs. PRIMER_MIN_*/PRIMER_MAX_* are HARD filters (a candidate outside them is eliminated); PRIMER_OPT_* plus the PRIMER_WT_* weights only RANK the survivors. Over-tightening BOUNDS is what returns zero pairs; changing weights only re-orders. The defaults are an opinionated weight vector (Tm and size dominate; GC-percent weights are 0 by default), not an objective truth.

How primer3 Scores: Weighted Penalty Minimization

Each tunable property has an OPT target and a weight (often split into _LT/_GT for below/above optimum). The per-oligo penalty is the weighted sum of deviations; the pair penalty adds pair terms (PRIMER_PAIR_WT_DIFF_TM for Tm mismatch, product-size deviation, cross-complementarity). Pairs are sorted ascending by PRIMER_PAIR_<i>_PENALTY; index 0 is the minimum. Two consequences the agent must act on: (a) raise PRIMER_PAIR_WT_DIFF_TM if a Tm-matched pair matters more than tight product size, and a different pair rises to index 0; (b) to forbid something use a BOUND, to merely discourage it raise a WEIGHT.

Tool Taxonomy

Decision Tree by Scenario

Default when uncertain: standard amplicon with SEQUENCE_TARGET, Tm 58-62 C, GC 40-60%, product 100-1000 bp, then route the top pairs to primer-specificity before ordering.

Design a Tm-Matched Primer Pair

Goal: Get ranked primer pairs that amplify the target region within the desired size and Tm window, Tm-matched between the two primers.

Approach: Put per-template data (the sequence and any positional constraint) in seq_args under SEQUENCE_* keys; put run-wide settings (Tm/GC/size bounds, salt) in global_args under PRIMER_* keys; call design_primers; read the ranked pairs from the flat result dict. Supply the real reaction salt so the reported Tm is meaningful.

import primer3

template = 'ATGC...'  # the only sequence primer3 sees

result = primer3.design_primers(
    seq_args={
        'SEQUENCE_ID': 'amp1',
        'SEQUENCE_TEMPLATE': template,
        'SEQUENCE_TARGET': [400, 60],          # [start, length], 0-based; both primers must flank this
    },
    global_args={
        'PRIMER_PICK_LEFT_PRIMER': 1,
        'PRIMER_PICK_RIGHT_PRIMER': 1,
        'PRIMER_NUM_RETURN': 5,
        'PRIMER_OPT_SIZE': 20, 'PRIMER_MIN_SIZE': 18, 'PRIMER_MAX_SIZE': 25,
        'PRIMER_OPT_TM': 60.0, 'PRIMER_MIN_TM': 58.0, 'PRIMER_MAX_TM': 62.0,
        'PRIMER_PAIR_MAX_DIFF_TM': 2.0,        # keep the pair within 2 C of each other
        'PRIMER_MIN_GC': 40.0, 'PRIMER_MAX_GC': 60.0,
        'PRIMER_PRODUCT_SIZE_RANGE': [[150, 400]],
        'PRIMER_SALT_MONOVALENT': 50.0,        # mM; match the reaction (drives Tm)
        'PRIMER_SALT_DIVALENT': 1.5,           # mM Mg2+
        'PRIMER_DNTP_CONC': 0.6,               # mM; subtracted from Mg2+ to get free Mg2+
        'PRIMER_DNA_CONC': 50.0,               # nM oligo
        'PRIMER_EXPLAIN_FLAG': 1,              # so a zero-pair run is diagnosable
    })

for i in range(result['PRIMER_PAIR_NUM_RETURNED']):
    print(result[f'PRIMER_LEFT_{i}_SEQUENCE'], result[f'PRIMER_RIGHT_{i}_SEQUENCE'],
          round(result[f'PRIMER_LEFT_{i}_TM'], 1), round(result[f'PRIMER_RIGHT_{i}_TM'], 1),
          result[f'PRIMER_PAIR_{i}_PRODUCT_SIZE'], round(result[f'PRIMER_PAIR_{i}_PENALTY'], 2))

Positional Constraints: Get the Tag Semantics Right

These are the most error-prone keys; the distinctions are load-bearing. All coordinates are 0-based by default (PRIMER_FIRST_BASE_INDEX), and every interval is [start, length], NOT [start, end].

• SEQUENCE_TARGET = [start, length] -- a legal pair must FLANK the target (both primers outside, amplicon spans it). Use to force the amplicon to cover a feature.
• SEQUENCE_INCLUDED_REGION = [start, length] -- primers are CONFINED within it; no part of a primer may fall outside.
• SEQUENCE_EXCLUDED_REGION = [[start, length], ...] -- no primer may OVERLAP any listed interval (even by one base).
• SEQUENCE_PRIMER_PAIR_OK_REGION_LIST = [[lstart, llen, rstart, rlen], ...] -- per-pair windows for the left and right primer independently (-1 leaves a side free).
• SEQUENCE_OVERLAP_JUNCTION_LIST = [pos, ...] with PRIMER_MIN_3_PRIME_OVERLAP_OF_JUNCTION (default 4) and PRIMER_MIN_5_PRIME_OVERLAP_OF_JUNCTION (default 7) -- at least one primer must straddle a junction; the 3' overlap is the specificity-determining knob.
• SEQUENCE_FORCE_LEFT_START/_RIGHT_START (fix the 5' end) and _LEFT_END/_RIGHT_END (fix the 3' end) -- pin a primer to a known oligo while primer3 picks the partner.

The 3' End Governs Priming -- and 5' Tails Do Not Anneal

Polymerase extends only from a base-paired 3'-OH, so the terminal ~5 nt are the priming anchor: a 3'-terminal mismatch suppresses extension by orders of magnitude (Kwok 1990 Nucleic Acids Res 18:999), which is why primer3 weights 3'-end (_END) complementarity far above internal (_ANY). A GC clamp (PRIMER_GC_CLAMP, default 0; set 1) stabilizes the anchor, but a too-stable 3' end is double-edged -- it also anchors at off-target sites, so cap it with PRIMER_MAX_END_STABILITY (a positive stability magnitude for the 3'-terminal pentamer in kcal/mol, NOT a signed dG; library default 100.0 = effectively off; lowering to ~9 as a heuristic forbids over-stable ends). For a primer carrying a non-templated 5' tail (restriction site, Gibson arm, T7 promoter, universal tail): design the template-binding CORE in primer3 so its Tm reflects only the annealing region, then prepend the tail in software; pasting the full tailed oligo into a Tm calculator overestimates the anneal Tm. The tail still exists physically, so check dimers/hairpins on the FULL tailed oligo (-> primer-validation).

Predicted Tm Is Not the Annealing Temperature

The Tm primer3 reports is an equilibrium midpoint against a perfect complement at the supplied oligo/salt concentration; the annealing temperature (Ta) the thermocycler runs is a separate operating point in a non-equilibrium reaction. A workable default is Ta ~3-5 C below the LOWER of the two primers' predicted Tm, then optimize empirically: a gradient PCR brackets the Ta giving a single product, and Rychlik's optimum (Ta_opt = 0.3Tm_primer + 0.7Tm_product - 14.9; Rychlik 1990 Nucleic Acids Res 18:6409) accounts for the product. When specificity is hard (paralogs, high background), use touchdown PCR (Don 1991 Nucleic Acids Res 19:4008): start Ta several degrees ABOVE the expected Tm so only the perfect target nucleates, then step down each cycle -- the specific product established first outcompetes later mispriming.