# Bio Primer Design Primer Validation

> Validates chosen PCR/qPCR oligos for intramolecular thermodynamic liabilities with primer3-py - hairpins, self-dimers, cross-dimers (calc_hairpin/homodimer/heterodimer), and 3'-end stability (calc_end_stability) - returning ThermoResult dG/Tm and ASCII structures. Covers why a "dimer-free" verdict is a PREDICTION at the supplied salt/Mg/dNTP/oligo conditions and temp_c (so the same primer is fine or dimer-prone depending on conditions), why a 3'-END dimer or hairpin is the lethal class (polymerase-extendable into primer-dimer) so structures are ranked by dG at the annealing temperature and 3'-end involvement rather than global Tm, that ThermoResult dG is in cal/mol not kcal/mol, and that .structure_found must gate the numbers. Use when checking primer pairs before ordering, troubleshooting primer-dimers or smears, or screening oligos for secondary structure. Genome off-target/mispriming is primer-specificity; design is primer-basics; probe assays are qpcr-primers.

- Skill: `pku-yuangroup/bio-primer-design-primer-validation` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add pku-yuangroup/bio-primer-design-primer-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pku-yuangroup/bio-primer-design-primer-validation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pku-yuangroup (https://skillmd.com/u/pku-yuangroup)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pku-yuangroup/bio-primer-design-primer-validation

---


## 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.calc_heterodimer)` 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.

# Primer Validation -- Thermodynamic Self-Structure of the Chosen Oligos

**"Are these primers free of dimers and hairpins?"** -> Predict the most stable intramolecular and inter-primer structures and judge them at the reaction conditions -- because a structure's harm is set by its dG at the annealing temperature and by whether it ties up the 3' end, not by a single global score.
- Python: `primer3.calc_hairpin(seq)`, `calc_homodimer(seq)`, `calc_heterodimer(seq1, seq2)`, `calc_end_stability(seq1, seq2)` return a `ThermoResult` with `.tm`, `.dg`, `.structure_found`.

Scope: thermodynamic validation of the OLIGOS themselves (hairpin, homodimer, heterodimer, 3'-end stability, pair Tm match) under stated conditions. Genome-wide off-target / mispriming / in-silico PCR -> primer-specificity. Designing primers -> primer-basics. qPCR primer+probe co-design -> qpcr-primers.

## The Single Most Important Modern Insight -- A "Dimer-Free" Verdict Is a Prediction at the Conditions Supplied, and the 3' End Is What Kills the Reaction

1. **These are predictions, not facts.** `calc_hairpin`/`calc_homodimer`/`calc_heterodimer` compute a dG/Tm under a specific monovalent/divalent/dNTP/oligo concentration and an evaluation temperature (`temp_c`). The same primer can read "fine" at default 37 C / default salt and "dimer-prone" at the real annealing temperature and Mg2+. Validate at the conditions and `temp_c` of the actual reaction, or the verdict is decorative.
2. **The 3' end is the lethal locus.** A dimer or hairpin that pairs the primer's 3' end is polymerase-EXTENDABLE: it gets turned into primer-dimer that amplifies exponentially, consumes reagents, and (in SYBR qPCR) generates competing signal. A structure with a more negative GLOBAL dG but a free 3' end is far less harmful. So do NOT rank by global dG or global Tm -- inspect 3'-end involvement (`calc_end_stability` and the ASCII structure) and judge at the annealing temperature.
3. **Read the units and the gate.** `ThermoResult.dg`, `.dh` are in cal/mol (and `.ds` in cal/(K.mol)) -- a value of -6000 is -6 kcal/mol, so divide by 1000 before comparing to kcal/mol heuristics. Always check `.structure_found` first: if no structure formed, the `.tm`/`.dg` are not a real duplex.

## The Three Structures, and Why They Differ

- **Hairpin** (intramolecular): the primer folds on itself; harmful mainly when it sequesters the 3' end or raises effective Tm enough to block template annealing.
- **Homodimer** (self-dimer): two copies of one primer pair; common with self-complementary or palindromic primers.
- **Heterodimer** (cross-dimer): the forward and reverse primers pair with each other. A primer can be individually clean and still cross-dimer with its partner, so the pair must be checked explicitly -- this is the dimer most often missed.

## Tool Taxonomy

| Function | Citation | Mechanism / role | When |
|----------|----------|------------------|------|
| `calc_hairpin(seq)` | Untergasser 2012 *Nucleic Acids Res* 40:e115 | most stable self-fold via thermodynamic alignment (ntthal) | screen a single primer/probe for hairpins |
| `calc_homodimer(seq)` | Untergasser 2012 *Nucleic Acids Res* 40:e115 | most stable self-self duplex | self-dimer of one oligo |
| `calc_heterodimer(s1, s2)` | Untergasser 2012 *Nucleic Acids Res* 40:e115 | most stable cross duplex of two oligos | forward-vs-reverse (and probe) cross-dimer |
| `calc_end_stability(s1, s2)` | SantaLucia & Hicks 2004 *Annu Rev Biophys* 33:415 | dG of the 3' end of s1 annealing to s2 | the 3'-anchored, extendable-dimer question |
| `calc_*_tm` (float) | Untergasser 2012 *Nucleic Acids Res* 40:e115 | the `.tm` only, no structure object | fast high-throughput screening |
| `calc_tm(seq)` | SantaLucia 1998 *PNAS* 95:1460 | nearest-neighbor Tm vs perfect complement | the pair Tm-match check |

## Decision Tree by Scenario

| Scenario | Recommended | Why |
|----------|-------------|-----|
| Standard pre-order check of a pair | `calc_hairpin`/`homodimer` on each + `calc_heterodimer` on the pair, at reaction conditions and `temp_c` = Ta | the four-call panel that catches self-structure |
| Suspect a primer-dimer artifact (gel, low-Tm melt peak) | `calc_heterodimer` + `calc_end_stability`, read the ASCII structure for 3'-end pairing | 3'-end dimers are extendable; that is the artifact source. A dimer that appears only at LOW template is diagnostic -- with scarce target, primer-primer collisions win the kinetic competition |
| Screening hundreds of oligos | `calc_hairpin_tm`/`calc_homodimer_tm` (floats) | fast triage; promote flagged ones to full `ThermoResult` |
| One primer designed with a 5' tail | run the calls on the FULL tailed oligo | the tail exists physically (palindromic sites/Gibson arms dimerize) |
| Pair anneals unevenly / one strand dominates | compare `calc_tm` of the two primers | a Tm mismatch >2-3 C, not a dimer, is the cause |
| "Will it amplify only the target?" | -> primer-specificity | that is genome off-target, a different question and toolset |

Default when uncertain: run the four-call panel at the real salt/Mg/dNTP/oligo concentrations with `temp_c` set to the annealing temperature, flag any structure whose dG is strongly negative at Ta, and weight 3'-end involvement most.

## Validate a Primer Pair at Reaction Conditions

**Goal:** Decide whether a chosen forward/reverse pair will misbehave through hairpins or dimers in the actual reaction, with the 3' end weighted appropriately.

**Approach:** Run hairpin and homodimer on each primer and heterodimer on the pair, all at the reaction's salt/Mg/dNTP/oligo concentrations and with `temp_c` set to the annealing temperature; gate every result on `.structure_found`; additionally compute `calc_end_stability` on the heterodimer to expose 3'-anchored (extendable) dimers; compare the two primer Tms for a match.

```python
import primer3

fwd, rev = 'GTCTCCTCTGACTTCAACAGCG', 'ACCACCCTGTTGCTGTAGCCAA'
COND = dict(mv_conc=50.0, dv_conc=3.0, dntp_conc=0.8, dna_conc=250.0, temp_c=60.0)  # match the qPCR/PCR reaction + Ta

def flag(label, res):
    if res.structure_found:
        print(f'{label}: Tm={res.tm:.1f}C dG={res.dg/1000:.2f} kcal/mol')   # dg is cal/mol -> /1000
    else:
        print(f'{label}: no structure')

for name, seq in [('fwd', fwd), ('rev', rev)]:
    flag(f'{name} hairpin', primer3.calc_hairpin(seq, **COND))
    flag(f'{name} homodimer', primer3.calc_homodimer(seq, **COND))

flag('heterodimer', primer3.calc_heterodimer(fwd, rev, **COND))
end = primer3.calc_end_stability(fwd, rev, **COND)            # 3'-end-anchored stability = the extendable-dimer risk
print(f"3'-end stability dG={end.dg/1000:.2f} kcal/mol")

dtm = abs(primer3.calc_tm(fwd, **{k: COND[k] for k in ('mv_conc','dv_conc','dntp_conc','dna_conc')})
          - primer3.calc_tm(rev, **{k: COND[k] for k in ('mv_conc','dv_conc','dntp_conc','dna_conc')}))
print(f'pair Tm difference={dtm:.1f}C')
```

## Reading the Result: dG, the 3' End, and the Structure

`ThermoResult.dg` is in cal/mol (divide by 1000 for kcal/mol). More negative = more stable = more concerning. But two structures with similar Tm can have very different dG at the annealing temperature, and the structure's own Tm is just where its dG crosses zero -- so judge by dG at `temp_c` = Ta, not by Tm. Print `res.ascii_structure` (or `res.ascii_structure_lines`) to SEE where the duplex sits: a dimer that pairs the recessed 3' ends is extendable and disqualifying even at modest dG, while a stronger structure with free 5'/internal pairing only transiently lowers free primer. `calc_end_stability(fwd, rev)` isolates exactly the 3'-end-of-fwd-against-rev stability, which is the right number for "will this dimer extend." It scores the 3' end of the FIRST argument, so check both directions (also `calc_end_stability(rev, fwd)`) -- either primer's 3' end can anchor the extendable dimer.

## Per-Method Failure Modes

### Ranking dimers by global dG or Tm
**Trigger:** Accepting/rejecting a structure on its overall dG or Tm. **Mechanism:** a weak dimer that locks the 3' ends is extended into artifact, while a strong dimer with free 3' ends is benign. **Symptom:** a "passing" pair still produces primer-dimer; a "failing" pair amplifies fine. **Fix:** inspect 3'-end involvement (`calc_end_stability`, ASCII structure) and weight it above whole-molecule dG.

### Validating at the wrong temperature/conditions
**Trigger:** Using default `temp_c=37` and default salt instead of the reaction's Ta and Mg2+. **Mechanism:** structure stability is strongly condition-dependent; a structure that melts below Ta is harmless. **Symptom:** false alarms (or false passes) that do not match the bench. **Fix:** set `temp_c` to the annealing temperature and pass the real mv/dv/dntp/dna concentrations.

### Trusting dG without a structure
**Trigger:** Reading `.dg`/`.tm` without checking `.structure_found`. **Mechanism:** when no structure forms the fields are not a real duplex. **Symptom:** nonsense or contradictory numbers. **Fix:** gate every result on `.structure_found` before reporting.

### Unit confusion (cal vs kcal)
**Trigger:** Comparing `.dg` directly to a kcal/mol threshold. **Mechanism:** primer3-py reports dG in cal/mol, so -6000 is -6 kcal/mol. **Symptom:** thresholds off by 1000x; everything looks catastrophic or fine. **Fix:** divide `.dg` by 1000 before comparing.

### Validating only the binding core of a tailed primer
**Trigger:** Checking the template-binding portion of a primer that carries a 5' tail. **Mechanism:** the full oligo (tail included) is what physically exists; palindromic restriction sites and complementary Gibson arms dimerize. **Symptom:** clean validation, dimers on the bench. **Fix:** run the calls on the FULL tailed oligo.

## Quantitative Thresholds

These are FLAGGING heuristics for inspection, not hard cutoffs; they are condition-dependent (salt, Mg2+, primer concentration, Ta). Read the structure and judge at Ta before accepting or rejecting.

| Threshold | Source | Rationale |
|-----------|--------|-----------|
| Hairpin Tm at least ~10 C below Ta | SantaLucia & Hicks 2004 *Annu Rev Biophys* 33:415 | a hairpin that melts well below the anneal step is largely denatured |
| Dimer dG flag if more negative than ~ -6 to -9 kcal/mol | -- | common practice line; below ~ -9 generally rejected; condition-dependent |
| 3'-END dimer dG: be stricter, flag ~ -3 to -5 kcal/mol | Kwok 1990 *Nucleic Acids Res* 18:999 | 3'-anchored dimers are extendable, so weight them above global dG |
| Pair Tm difference <= 2 C | Koressaar & Remm 2007 *Bioinformatics* 23:1289 | matched Tm so both primers anneal at one Ta |
| Evaluate at `temp_c` = annealing temperature | SantaLucia & Hicks 2004 *Annu Rev Biophys* 33:415 | dG at Ta, not at 37 C, is the harm-relevant quantity |

## Common Errors

| Error / symptom | Cause | Solution |
|-----------------|-------|----------|
| `AttributeError: calcHeterodimer` | camelCase deprecated since primer3-py 1.0.0 | use snake_case `calc_heterodimer` |
| Validation disagrees with the bench | default `temp_c`/salt, not the real reaction | pass reaction mv/dv/dntp/dna and `temp_c` = Ta |
| A "clean" pair still makes primer-dimer | judged by global dG, missed the 3' end | check `calc_end_stability` and the ASCII structure |
| dG threshold seems 1000x off | `.dg` is cal/mol, not kcal/mol | divide by 1000 before comparing |
| `.tm`/`.dg` look meaningless | no structure formed | gate on `.structure_found` |
| Pair amplifies one strand only | Tm mismatch, not a dimer | compare `calc_tm` of the two primers; redesign Tm-matched (primer-basics) |

## References

- Untergasser A, Cutcutache I, Koressaar T, et al. 2012. Primer3 - new capabilities and interfaces. *Nucleic Acids Res* 40:e115.
- SantaLucia J Jr, Hicks D. 2004. The thermodynamics of DNA structural motifs. *Annu Rev Biophys Biomol Struct* 33:415-440.
- SantaLucia J Jr. 1998. A unified view of polymer, dumbbell, and oligonucleotide DNA nearest-neighbor thermodynamics. *PNAS* 95:1460-1465.
- Koressaar T, Remm M. 2007. Enhancements and modifications of primer design program Primer3. *Bioinformatics* 23:1289-1291.
- Kwok S, Kellogg DE, McKinney N, et al. 1990. Effects of primer-template mismatches on the polymerase chain reaction: human immunodeficiency virus type 1 model studies. *Nucleic Acids Res* 18:999-1005.

## Related Skills

- primer-basics - Design Tm-matched primer pairs (redesign if validation fails)
- primer-specificity - Genome-wide off-target / in-silico PCR (a different question)
- qpcr-primers - Co-design qPCR primers and probes, including probe self-structure
- sequence-manipulation/seq-objects - Reverse-complement and assemble tailed oligos to validate