Site-saturation mutagenesis

Pick the residues you want to randomise and get the primer pairs that saturate them in one reaction.

What it doesCopy Anchor Link

You name the residues you want randomised, and it designs the mutagenic primer pairs that saturate them — replacing each whole codon with a degenerate one, so a single reaction produces a library containing every amino acid you asked for at every position you named.

The hard part is not the degenerate codon; it is making several primer pairs work in one tube. Each pair must anneal in the same temperature window as all the others, carry enough correctly matched sequence on both sides of the change to bind at all, and not fold back on itself or pair with its neighbours. The design searches that space — over primer lengths, 5′ and 3′ arm sizes and overlaps — and returns the set whose temperatures agree most closely. Two searches are offered and they look at different amounts of that space; which one ran is stated with every result.

When you’d use thisCopy Anchor Link

• You have a candidate residue and no hypothesis about what should replace it. Saturating it and screening the library answers the question a single designed substitution only guesses at.
• You have several such residues and one experiment's budget. SSM designs them as one set, so they can be run together instead of as N separate reactions at N different annealing temperatures.
• You are building a focused library rather than a random one. Error-prone PCR randomises everywhere; this randomises exactly where you say, which is what makes the hits interpretable.

The usual route is: pick the CDS → list the sites → choose the degenerate codon → design → read the temperature spread → place the primers on the map → export the order list. For specific substitutions rather than saturation, use Site-Directed Mutagenesis for one and Multi-site mutagenesis for several. To choose which amino acids appear at each site rather than all of them, use the Library tab.

What this computesCopy Anchor Link

A saturation design is a search, not a formula. For every candidate primer the design computes two temperatures separately, because they govern different things:

• The whole-oligo melting temperature, which governs whether the primer anneals at all
• The 3′-end melting temperature, which governs whether the polymerase extends from it

It then chooses the combination across all sites whose temperatures fall in the tightest common window, so one cycling programme suits every pair.

Two searches, and you choose which one runsCopy Anchor Link

The step that differs between them is how the candidates are produced, and it is a real choice rather than a speed setting — they can return different primers for the same request.

• Fast approximation (the default). For each reaction temperature tried, it picks an overlap and grows one forward and one reverse primer outward from it, base by base, until the 3′-end temperature target is met. One candidate pair per site per temperature. It returns in milliseconds, and it is the published tool's own default.
• Exhaustive search. For each site it enumerates every legal primer spanning it — every combination of 5′ arm, mutated triplet and 3′ arm within the size bounds — keeps every pair whose shared overlap is an allowed length, and scores all of them at every reaction temperature. On a typical CDS that is hundreds of thousands of pairs per site and hundreds of millions of scored pairs in total, so it takes seconds rather than milliseconds. It runs off the main thread and can be stopped.

The exhaustive search reports what it actually searched — candidates enumerated, how many survived the arm-size limits, pairs scored, reaction temperatures tried — so the cost of the choice is a number you can read rather than a claim. The fast approximation reports no such count, because it enumerates nothing.

Two size limits only exist under the exhaustive search, and the panel shows them only there: the longest 3′ arm and the longest 5′ arm. The fast approximation grows each arm outward until it meets a temperature target, so it takes a floor and has no use for a ceiling; the exhaustive search uses both to bound the region it enumerates and to discard candidates that overrun it.

• Candidates scored on melting temperature, length, arm sizes, GC content and — when you ask for it — hairpin and dimer penalties, with every weight exposed as a control
• Melting temperatures from a nearest-neighbour model with salt and magnesium corrections
• The 3′ window derived from your flanking primer pair's two temperatures, which is why those primers are not decoration: change them and the design changes. Each must occur exactly once in the sequence

Every run also states, in words, what it decided and what it cost:

• The one overlap and 3′-end melting temperature the whole reaction settled on, and how far that is from the optimum you aimed at
• Which sites fall outside a window you set, and the worst of them by non-optimality — the score of how far a site sits from the shared target. This is the ordinary price of designing every site for a single tube, not a failed design, and the reading says so rather than leaving a warning mark to be read as an error
• Which sites could not be placed at all, distinguished from those placed outside a window, since the two call for different fixes
• Whether secondary structure was ranked or only reported, because the hairpin and dimer energies are always measured and only affect the ranking when you ask them to

Sites are written <wild type><position>X; the target letter is X because saturation replaces the whole triplet, and anything else there is accepted and ignored.

Where it livesCopy Anchor Link

Tools → Site-Directed Mutagenesis → the Saturation tab, from the command palette, or by right-clicking a CDS feature on the map — which opens the panel already pointed at that gene.

Picking a coding sequence selects it on the map, so the gene you are about to randomise is visible while you work on it. Designed primers can be written onto the map as real annotations at their true coordinates.

Inputs and outputsCopy Anchor Link

In: a coding sequence — any CDS feature on the open record, or a selection you make yourself — plus the list of sites, written as <wild type><position>X, one per line or space-separated. The target letter is X because saturation replaces the whole triplet; anything else there is accepted and ignored.

You also need a flanking primer pair. These are not decoration: the 3′ melting-temperature window the solver aims for is derived from their two melting temperatures, so they change the design. Each must occur exactly once in the sequence, and use plasmid defaults fills them from the sequence around your gene.

Out: one mutagenic primer pair per designed group, each with its length, melting temperature, GC content, folding energy, hairpin and self-dimer energy, cross-dimer with its partner, and 3′-end stability. Primers can be placed on the map or exported as CSV.

What it refuses, and what it says. Nothing fails silently:

• A gene that is not a whole number of codons → "…is 721 bp, not a multiple of 3 — its codons cannot be addressed."
• A site that names no residue → "145 — 1 is not an amino-acid letter (write it as <WT><position><target>, e.g. Y66X)."
• A position past the end of the protein → "Position 9999 is outside egfp (1–239 residues)." The stop codon is not one of them: a 720 bp CDS has 239 addressable residues, not 240.
• Geometry that cannot produce a primer → the arithmetic is named, e.g. "Max primer size (12) is below the smallest legal primer (23 nt = 10 + 3 + 10)."
• Flanking primers missing, or occurring more than once in the sequence.

A wild-type letter that does not match your sequence is a warning, not a refusal. Saturation replaces the codon whatever it currently is, so the design stays chemically valid — what the wrong letter tells you is that your numbering is off, and that you are randomising a different residue from the one you meant. That is almost always an off-by-one between numbering conventions.

DemoCopy Anchor Link

Not recorded yet. A screencast belongs here and does not exist. The worked example below is a real run on a bundled starter, reproducible number for number.

Worked exampleCopy Anchor Link

Open the Site-directed mutagenesis starter and switch to the Saturation tab. It carries CVU55762, the real 4,733 bp pEGFP-N1 cloning vector, whose egfp CDS is 720 bp.

1. Target CDS → egfp (720 bp), then type two sites: T66X S203X.
2. Flanking primer pair → use plasmid defaults. These two Tms are what set the 3′ temperature window, so the design changes with them.
3. Design 2 sites.

The T66X pair comes back as 34 nt forward (3′ Tm 73 °C, GC 61.76 %) GTGACCACCCTGNNKTACGGCGTGCAGTGCTTCA and 36 nt reverse (3′ Tm 65 °C, GC 63.89 %) GAAGCACTGCACGCCGTAMNNCAGGGTGGTCACGAG — note MNN on the reverse strand, the reverse complement of NNK — over a 33 nt overlap at 85 °C, score 9. Each primer carries its own ΔG fold, hairpin, self-dimer, cross-dimer and 3′-end energies in kcal/mol.

Two things this run says out loud rather than hiding. 2 of 2 pairs fall outside the GC or Tm window — they are the best available under these settings, not an error, and widening the windows or the size range is the fix. And nothing is written to the record until you press Add 4 primers to the map.

Type the site as Y66X instead and the design is refused before it runs: "The wild-type letter does not match egfp. Y66X: position 66 is T (ACC), not Y (Y is at 67). Usually an off-by-one between numbering conventions." The classic eGFP chromophore numbering is one out against this CDS, and the message names both what is really at 66 and where the tyrosine you meant actually sits. Saturation would have installed a perfectly good degenerate codon at 66 either way, which is precisely why this is refused rather than warned about: the oligo would be fine and the answer would be about a different residue than the one you asked for.

ControlsCopy Anchor Link

• Target CDS — any coding feature on the open record, or your own selection.
• Sites to saturate — the list, as Y66X.
• Degenerate codon — a preset or your own. NNK (all 20 amino acids, one stop, 32 codons) is the default because it is the standard compromise: full amino-acid coverage with a single stop and no runaway over-representation of the six-codon families. NNS is equivalent on the other wobble; NDT gives 12 amino acids and no stop in 12 codons, which is the choice when library size rather than completeness is the constraint. Comma-separate several (NNK,NDT) to order a mixed set — the table shows the first, the CSV expands all of them.
• Flanking primer pair — see above; these set the 3′ temperature window.
• Optimise forward and reverse 3′ Tm independently — on by default. Off ties both strands to one window, which is stricter and sometimes finds no solution.
• Set the 3′ Tm window myself — takes the window out of the flanking primers' hands entirely.
• Penalise hairpins and primer dimers — runs the full thermodynamic model during the search rather than only reporting it afterwards. Roughly doubles the run (~90–210 ms off versus ~180–265 ms on, for three sites on a 720 bp gene), which is why it is a choice and not a default.
• Geometry, temperatures and score weights — for each of primer size, overlap size, 3′ arm size, GC content, overlap melting temperature and 3′-end melting temperature, all three of the minimum, the optimum and the maximum, plus the 5′ arm bounds, the scan step and tolerance, every scoring weight, the salt model and the oligo name prefix. None of these is a hidden default.
• The optimum is not the midpoint of its window — it is the value the score is a deviation from, so it is what actually decides the ranking among candidates that all pass the window. Raising or lowering one changes which design wins without changing which designs are legal. An optimum set outside its own minimum-maximum window is refused by name rather than run, because it would score every candidate against a target the search cannot reach.

Algorithms you can chooseCopy Anchor Link

One designer, and the choice inside it is the solver's arithmetic, not a menu of methods. This is Mutation Maker's SSM workflow: an overlap whose Tm is matched across every site, and primers grown outward from it until each 3′ end clears its temperature threshold.

The upstream library ships two solvers and this is the one it defaults to. ssm.py's exhaustive path enumerates candidates from the primer3 C designer and scores every valid pair; ssm_fast_approximation.py grows primers arithmetically from a chosen overlap, in pure Python. Upstream's own use_fast_approximation_algorithm defaults to True, and it is the only one of the two that runs in a browser at all, since the other needs the primer3 binary. This is that fast path, complete — the primer3-design path is a known gap, stated rather than approximated with something that would look like it.

What you do choose:

• The degenerate codon — NNK · NNS · NDT, or your own, or several comma-separated for a mixed order (see Controls for what each buys you).
• The melting-temperature model — a nearest-neighbour model with salt and magnesium corrections (SantaLucia, the default), or the GC-based formula a particular published protocol was calibrated against. The window is calibrated for the nearest-neighbour scale, so changing the model moves which pairs fall inside it.
• Whether the hairpin and dimer penalties run inside the search or are only reported after it. Inside is roughly twice the work (~90–210 ms off versus ~180–265 ms on, three sites on a 720 bp gene), which is why it is a control rather than always-on.
• Every geometry and weight — primer size bounds, 5′ and 3′ arm sizes, overlap size, the temperature scan bounds, the GC window and each score weight.

Bring your own: designSsm in @ports/mutagenesis is a plain function over a CDS and a site list, callable from the consoles with no editor state.

The scienceCopy Anchor Link

A saturation design is a search, not a formula. For each site the solver considers every legal primer that spans it — every combination of 5′ arm, mutated triplet and 3′ arm within the size bounds — and computes the melting temperature of the whole oligo and of its 3′ end separately, because those two numbers govern different things: the whole-oligo temperature governs whether the primer anneals at all, and the 3′-end temperature governs whether the polymerase extends from it.

It then chooses the combination across all sites whose temperatures fall in the tightest common window, so one cycling programme suits every pair. Candidates are scored on melting temperature, length, arm sizes, GC content and — when you ask for it — hairpin and dimer penalties, with every weight exposed as a control.

Melting temperatures come from a nearest-neighbour model with salt and magnesium corrections (SantaLucia by default), or the GC-based formula a particular published method was calibrated against. Hairpin, self-dimer, cross-dimer and 3′-end stability are real thermodynamic calculations over the actual sequence, not heuristics.

On correctness: the design engine is checked against the original published implementation field by field — every melting temperature, every primer, every score — over the whole set of captured cases rather than a sample.

LimitationsCopy Anchor Link

• Saturation is not selection. The tool designs the library; it does not predict which substitutions will help. No stability or fitness score is shown, because showing an approximated one would be inventing a number.
• The library is not persisted as an object yet. A design can be exported and placed on the map, but there is no stored "variant library" record to return to.
• NNK carries a stop codon in 1 of its 32 codons. That is inherent to the codon, not to this tool, and it is why the preset says so. Use NDT if a stop in the library is unacceptable.
• The published method's solver has two paths, and the faster one is what runs here. The alternative drives an external command-line designer that cannot run in a browser; the method's own default is the fast path, so this is its production behaviour rather than a reduced version of it.
• Sites too far apart to share a primer get their own pair — correct, but it means more components in the reaction. The design tells you how many pairs it needed.

Compared with other toolsCopy Anchor Link

Sources, first-party and dated: https://www.snapgene.com/features, retrieved 2026-08-08, quoted verbatim. Geneious Prime's feature page (https://www.geneious.com/features, same date) does not name mutagenesis among its cloning tools.

Read the blanks honestly: "not listed" means the vendor's own feature page does not name it, not that the product cannot do it. Neither is runnable here to check. The tool this one is closest to is not a commercial suite at all — it is Mutation Maker (Merck, GPL-3), which is what this is a port of, and which the comparison is made against.

ExportCopy Anchor Link

• CSV — every primer with its sequence, length, melting temperature, GC and the four thermodynamic energies. A mixed degenerate order (NNK,NDT) expands to one row per codon.
• Onto the map — primers become real annotations at their true coordinates, so they live in the record, in version history, and in whatever you export it as.
• Copy — each sequence individually, forward or reverse.

APICopy Anchor Link

@ports/mutagenesis — the design, with no editor state:

import { SSM_CONFIG_DEFAULTS, ssmSolve } from '@ports/mutagenesis';

const out = ssmSolve({
  sequences: { gene, forwardPrimer, reversePrimer },  // the flanking pair sets the 3' window
  mutations: ['T66X', 'S203X'],                       // 1-based residues; the letter is checked
  config: { ...SSM_CONFIG_DEFAULTS /* geometry · temperatures · weights */ },
});

Back comes one forward/reverse pair per site, each with its length, whole-oligo and 3′ Tm, GC, the four thermodynamic energies, the shared overlap and its Tm, and the pair's score — plus the reaction-level window every site was matched into. SSM_CONFIG_DEFAULTS is upstream's own default set, so calling it with nothing but sequences and mutations reproduces what the panel does with its controls untouched. Temperature precision above one decimal place is refused, faithfully to upstream, rather than silently accepted and slow.

ssmSolveExhaustive takes the same argument and returns the same shape plus a search field — the candidates it enumerated, how many survived the arm-size limits, the pairs it scored and the number of reaction temperatures it tried. It reads maxThreeEndSize and maxFiveEndSize, which the fast solver ignores. It is the second search described above and it takes seconds, so call it from a worker.

The saturation-library arithmetic is separate and lives in the app's own engine: designSaturationLibrary takes the CDS target, the per-site requests and a strategy — multi-site (every site at the same codon count, because one primer carries one codon per site) or site-separate (each site solved independently, correct when the sites go on separate primers) — and returns the reachable codon sets, the per-site amino-acid coverage and the library diversity, the product of each site's reachable amino-acid count. It throws with a specific, actionable message rather than returning an empty result: an out-of-range position, a site with no requested amino acids, an amino acid the codon table cannot encode, or the upstream "sites cannot be covered by equal-length primer sets" condition — which is a real protocol constraint, not a bug.

AutomationCopy Anchor Link

• The copilot and the workflow DAG reach the point-mutagenesis half through design_mutagenesis_primers (category design, a write node, so it goes through the approval gate). It takes a CDS and a change written as [WT][pos][MUT] — W140F — and returns the mutant codon, the wild-type codon it replaces, the 0-based nucleotide offset, how many nucleotides changed, and the candidate inner primer pairs with their Tms.
• The saturation design has no DAG node of its own today. It is driven from this panel, or by calling designSsm from the Python or JavaScript console, which is the honest state of it rather than a step that would take half the parameters. The gap is stated here rather than left to be discovered.
• A mixed degenerate order (NNK,NDT) expands in the CSV, one row per codon, which is the batch path for ordering: design once, export once, hand the file to a vendor.

ProvenanceCopy Anchor Link

Nothing is written to your record until you say so. The designed primers are a proposal — Add N primers to the map is what turns them into real annotations at their true coordinates, and only then do they enter the record, its version history and whatever you export it as. That is why the panel says "Nothing is written to the record until you confirm" under the button.

Once added, the primers are ordinary annotations, so the record's own step log carries them like any other edit and a version restore brings back exactly the set that was added.

What makes a run reproducible is the question, and the panel shows all of it: the CDS and its length, the sites, the degenerate codon, the flanking pair whose Tms set the window, whether the thermodynamic penalties ran inside the search, and every geometry and weight (behind Show geometry, temperatures and score weights — none of them is a hidden default). Given those, the design is deterministic.

Citing the method: this is a port of Mutation Maker's SSM workflow (Merck, GPL-3) — the fast approximation path, which is upstream's own default — with melting temperatures from the nearest-neighbour model you selected. The comparison is made against that library and can be re-run, so the numbers in a paper can be re-derived rather than trusted.

ScreenshotsCopy Anchor Link

T66X and S203X on the 720 bp egfp CDS of CVU55762, designed as one reaction: the matched temperature windows (forward 3′ 73.6 °C, reverse 3′ 65.0 °C, overlap 84.0 °C), where the four primers land on the gene, and each pair's sequence with its own ΔG fold, hairpin, self-dimer, cross-dimer and 3′-end energies. The amber line is the panel saying that both pairs fall outside the GC or Tm window — the best available under these settings, and what to widen to improve them — and the note under the button says nothing is written to the record until you confirm.

RelatedCopy Anchor Link

In this group: Restriction Digest · Ligation · Gibson Assembly · Golden Gate Assembly · Grammar Assembly · Assembly Plan · Recombination Cloning · Site-Directed Mutagenesis · Multi-site mutagenesis