Grammar Assembly

Check that a part obeys the assembly syntax it claims, then assemble parts that do.

What it doesCopy Anchor Link

Modular cloning standards — MoClo, GoldenBraid and their relatives — work because every part carries the same four-base overhangs in the same places, so a promoter always joins a coding sequence and never a terminator. That syntax is the whole point, and it is also the thing that is easy to get wrong: a part that looks like a promoter but was built with the wrong flanks will fail silently in the tube.

This panel does two things about that. First it classifies each part by digesting it and reading the overhang pair that comes out — which grammar it belongs to, which level it is, and which position in a transcription unit it can occupy. Then it assembles the parts that agree, reporting every construct their overhangs allow rather than the first one it finds.

When you’d use thisCopy Anchor Link

Used in: Clone an insert into a vector, and prove it worked

What this computesCopy Anchor Link

Two questions, kept apart, because one is about the parts and the other about what they can make.

Classification, from the sequence rather than from the name

• Each part digested and its overhang pair read — the four bases at each end that decide what it can join
• How many times the release enzyme actually cut, and, when that is more than twice, which fragment is the module and which are its carrier — so a part delivered in a vector that carries its own site for the same enzyme still reads as the part it is
• Which grammar it belongs to, which level it is, and which position in a transcription unit it can occupy, derived from those overhangs. A part that looks like a promoter but was built with the wrong flanks is caught here rather than in the tube
• The parts that fit no grammar, named, rather than dropped
• Whether the matched position is a composite — one part occupying several consecutive slots, so a cassette assembled as a single piece is not mistaken for a missing promoter and terminator
• Whether a part is also the backbone its level assembles into, which some kits define as a positioned part rather than as a separate vector
• The sites a part must NOT carry, and the positions exempted from that — a few standard parts are defined by retaining the assembly enzyme's site, so scrubbing it would destroy them

Assembly, exhaustively

• Every construct the overhangs allow, not the first one found — because a set of parts with ambiguous flanks makes several products, and knowing that is the finding
• The slots and the parts competing for each, so a position two parts can both fill is visible as a choice rather than resolved silently
• The unused parts, with the reason each was not placed

How many constructs, against how many were possible

• The combinatorial upper bound, counted from the positions two or more parts can both fill. A reaction whose parts share a slot is a library, not a failed single assembly, and the number of products means little without the number that were possible
• The constructs that actually closed, and therefore how many combinations did not — a combination the bound allows can still fail to circularise
• The parts the enzyme cannot release, named. A part flanked by fewer than two sites of the chosen Type IIS enzyme contributes nothing and is absent from every product; this is the commonest reason a part is missing from a construct, and an already-assembled unit is not cut by the enzyme that built it
• The fusion sites joining each pair, with the overhang width the chosen enzyme actually cuts (four bases for BsaI, BsmBI or Esp3I; three for SapI) — the width is what makes the assembly order forced rather than chosen

Where it livesCopy Anchor Link

Tools → Grammar Assembly (MoClo/GoldenBraid), in three tabs: Parts Bin for adding and classifying parts, Constructor for choosing which of them go into a reaction, and Grammars for the position tables themselves.

Inputs and outputsCopy Anchor Link

In: circular part plasmids. A grammar part is a plasmid whose insert is released by digesting the ring, so the parts bin takes circular records — from the open plasmid, from a selection on the canvas, from a file in your project, from a database fetch, or pasted as bases. Each part is then classified by its own flanking overhangs: its grammar, its level, and the position it can occupy in a transcription unit.

Four ways in, and they differ only in where the bases come from:

• Add open plasmid — whatever is on the canvas now.
• Add selection — the region you have selected, added as a linear part. It will sit in the bin unclassified, because classification digests a ring; use it to stage a sequence you are about to domesticate, not as a finished part.
• Import from project file — a list of every sequence record in the project with its length beside it; click one to add it. Only the record you click is read, so the list is immediate even in a project of large files.
• Fetch from database — a record from NCBI, ENA, UniProt or Dbfetch, parsed by the same reader as everything else, so a fetched part behaves identically to an imported one.

What it refuses, and what it says. A fetched linear record is refused by name, with the reason — a grammar part is a circular plasmid, and adding one only to have the classifier correctly decline it a moment later reads as the classifier failing rather than as the input being wrong. A multi-record fetch adds every circular record it holds and reports how many linear ones it skipped, rather than dropping them silently.

Unclassified is a result, not a rejection. A part that no known grammar could release as a clean two-fragment digest with recognised overhangs is added and marked unclassified, and the panel says exactly that. It is often the correct answer: universal domesticators and destination vectors are legitimately unclassified, because they are not positional parts. The assembly report says so too — it names each unclassified part and warns that the position checks cannot cover it, rather than letting their absence from those checks read as a pass.

DemoCopy Anchor Link

No screencast yet. The sample project is one click from the lobby and arrives with its parts bin already filled, so the worked example below is reproducible in two presses.

Worked exampleCopy Anchor Link

Open the Grammar assembly (MoClo) sample. Its parts bin arrives holding ten real part plasmids — entry vectors, two coding sequences, and two already-assembled transcription units — with four acceptors configured (Alpha1, Alpha2, Omega1, Omega2). Switch to Constructor and press Assemble with Esp3I.

What comes back is not one construct:

• The parts each declare their overhang pair in the selected-parts list — GGAG→GTCA, GTCA→CGCT, AATG→GCTT — which is what says a part can follow another at all.
• Sixteen fragments come out of the digest, each captioned with its length and its two overhangs: 854 bp · GGAG … GTCA, 1,846 bp · GTCA … GGAG, and so on. They are drawn on one shared scale, so an 854 bp off-cut and a 1,846 bp insert are the sizes they really are.
• The connections graph shows which fragments can clip together; the slots graph resolves them into 5 slots over 7 distinct overhangs, and its numbered legend is the finding: slots 3, 4 and 5 each hold two parts. That is a combinatorial library, not a construct — the same parts list yields twelve valid assemblies, and the run reports all of them.
• The errors spreadsheet says what did not take part: unused_parts: FFE_10_CDS_cscA & FFE_11_CDS_cscB & FFE_1_ENTRY_UPD & FFE_6_ENTRY_pCambia2300_GREE. Four of the ten parts are named rather than quietly dropped, which is the difference between a result and a shrug.

ControlsCopy Anchor Link

Algorithms you can chooseCopy Anchor Link

The choice here is the grammar, not the algorithm. Classification and assembly are one method; what you pick is which published position table they are read against — Golden Braid L0, MoClo Plant (Weber 2011), the Yeast ToolKit (Lee 2015), CIDAR (Iverson 2016), EcoFlex (Moore 2016), or a grammar you define. Changing it changes which overhang pair means promoter and therefore what each part in your bin is, which is a much larger change than swapping a solver would be.

Bring your own: the Python and R consoles mount the project's files, so a parts-standard checker you already trust runs over the same plasmids in the same browser tab.

The scienceCopy Anchor Link

A part is classified from one input, and it is the honest one: the overhang pair a Type IIS digest actually releases from the ring. Not the record's name, not a feature annotation, not a filename — the two four-base single strands, 5′ and 3′, that the enzyme leaves on the excised insert. Everything else about a part can be aspirational; those two cannot.

Classification runs in four passes, and all four matter:

1. The position table — does this overhang pair name a position in the grammar (promoter, CDS, terminator, and the rest)?
2. The canonical transcription-unit boundary — is this a whole TU rather than a part of one?
3. Per-acceptor entry-vector stuffer pairs — does it match one of the acceptors you configured, which is what places a TU in Alpha1 rather than merely identifying it as a TU?
4. A lenient TU pass via the backbone-marker split, for a unit whose flanks do not match canonically.

Passes 3 and 4 were absent from an earlier version of this engine, and their absence was not cosmetic: the two assembled transcription units in the shipped sample set classified as nothing at all.

Assembly is overhang complementarity over the digested fragments, searched for every path that closes — so a parts list with two candidates for a slot reports both constructs rather than picking one.

Before the reaction: which parts this enzyme can actually releaseCopy Anchor Link

A Golden Gate reaction returns nothing far more often because of the enzyme than because of the grammar, and the panel checks that before you spend anything. Every selected part is searched for recognition sites, and a part that does not carry exactly two flanking ones is named:

• No recognition site — this part will not be cut. Almost always a level mismatch rather than a broken part. An assembled transcription unit is not cut by the enzyme that built it: BsaI released the L0 parts and joined them, so the finished unit carries no BsaI site and needs the level-up enzyme instead. Seeing your TUs flagged under BsaI is the tool telling you that you are one level too low.
• Only one site — this part is a dead end. One cut opens the ring but releases nothing, so the part can enter an assembly and never leave it.
• N internal sites — this part will be mis-cut. The enzyme cuts inside the insert as well as at the flanks, so the fragment that comes out is not the one you drew. This is what domestication is for, and it is the one case where the part itself needs changing.

A third site is not automatically an internal one, and the count says which it is. A Level-0 part supplied in a universal domestication vector often carries a site for the assembly enzyme in the vector's own backbone — the standard GoldenBraid pUPD parts do, so a promoter or terminator delivered in one is cut three times, not twice. Nothing is wrong with such a part: the extra cut falls between the two backbone pieces, the module still comes away flanked by its own two fusion sites, and domesticating it would change a sequence that is already correct. The check distinguishes them by asking which released fragment carries the origin and resistance markers and which does not, so a backbone site is reported as a backbone site and only a cut falling inside the module is called internal. This needs the part's annotations; on an unannotated sequence the two cannot be told apart, and the check deliberately reports the louder answer — a needless domestication costs you a step, a missed internal site costs you the construct.

None of these stop the run, and that is deliberate: a part the enzyme cannot cut does not make the reaction impossible, it simply does not participate. The assembly proceeds with the parts that can be released, and the flagged names tell you why the product list is shorter than your selection. The single case that does stop it is the enzyme cutting nothing — then there is no reaction to run at all.

The practical habit this supports: select everything, read which parts drop out, and let that tell you what level you are assembling at.

The two numbers that decide whether a grammar can accept your partCopy Anchor Link

Every grammar in the panel states two facts about itself, and between them they answer most of "why did this not classify?".

The transcription-unit boundary is the overhang pair a finished unit of that grammar presents to the level above: the 5′ overhang of its first position and the 3′ overhang of its last. Golden Braid L0 and MoClo Plant both end up at GGAG→CGCT, which is why an assembled unit from either can go into the same acceptor — that shared boundary is the whole point of a standard, and it is the thing to check first when a level-up reaction refuses to close. It is not always fixed: the Yeast ToolKit closes at CCCT→CCCT, and CIDAR deliberately leaves both ends open, because varying the outer overhang is how several CIDAR cassettes are ordered into one circuit.

The canonical fusion sites are every position overhang in the grammar plus its reverse complement, because a fragment can arrive in either orientation and the classifier has to recognise it both ways. The count is the size of the grammar's vocabulary: 22 sites for Golden Braid L0 over its 18 positions, 12 for MoClo Plant over its 5, 22 for the Yeast ToolKit over its 17, 10 for EcoFlex over its 7 and 6 for CIDAR over its 4. A part whose ends are not in that set is not a broken part — it is a part from a different standard, or a part whose flanks were designed by hand — and it will be listed as unclassified rather than forced into the nearest slot.

The practical reading: a grammar with more positions is not a "better" grammar, it is a finer one. Golden Braid L0 can tell a distal 5′ UTR from a proximal one; MoClo Plant cannot, and does not claim to. Choosing between them is choosing how much resolution your part set actually has.

On correctness. The grammar model, the four classification passes and the built-in Golden Braid and MoClo Plant position tables are ported algorithm-for-algorithm from the published implementation and checked against it case for case, with the source kept so the reference vectors stay regenerable. One deviation is deliberate and architectural rather than behavioural: the published version reads entry vectors off disk, and this engine takes them already parsed, because it does no file IO. With none supplied it returns exactly what the original returns with an empty entry-vector file, which is pinned as its own case.

LimitationsCopy Anchor Link

• Classification digests a ring. A linear part added from a canvas selection sits in the bin unclassified, and that is correct rather than a gap: there is no digest to read an overhang pair from. Use it to stage a sequence you are about to domesticate, not as a finished part.
• A part that is syntactically valid can still be biologically wrong. The overhangs say a promoter may join this coding sequence; they say nothing about whether it will express it.
• Ligation fidelity is not scored here. Whether two overhangs can join is a syntax question and is answered; how often T4 ligase actually joins them is measured data that Golden Gate Assembly reports.
• A combinatorial parts list produces a combinatorial answer. Twelve constructs from ten parts is the correct result, not an error — but it means "the product" is a library, and picking one is your decision.

Compared with other toolsCopy Anchor Link

Left unwritten rather than filled with a table we cannot source: the rule for this section is that every row carries a first-party source and a retrieval date, and the modular-cloning tools have not been surveyed to that standard here yet. What can be said without one is what this panel's own design commits to: a part is classified from the overhangs a digest releases rather than from what it is called, and every construct the parts allow is reported rather than the first one found.

ExportCopy Anchor Link

The constructs as CSV, the errors and warnings each as their own CSV, and the whole run as Markdown or as a plain text table. Any product opens as a new record in the project, carrying the parts it was built from.

APICopy Anchor Link

Classification and assembly are available headlessly, so a parts bin can be checked without the panel. Entry vectors are passed in already parsed rather than read from disk, which is what keeps the engine free of file IO and makes a run reproducible from its inputs alone.

Separately, the editor's Python and R consoles see the open record and the project's files in both languages, so a standards checker written elsewhere can be run over exactly these plasmids.

AutomationCopy Anchor Link

The classification and assembly steps are callable by the scientific copilot, so "which of these plasmids are valid L0 parts, and what do they assemble into" can be asked of a project rather than clicked through part by part.

ProvenanceCopy Anchor Link

A run records the grammar, the enzyme it digested with, the parts it took and the classification each of them received, and — for every product — the parts it was assembled from and the overhangs at each junction. The errors and warnings travel with it, so which parts went unused survives into the record rather than living only on screen.

Citing the method means naming the grammar standard your parts follow and the Type IIS enzyme used, since those two together are what makes the syntax check meaningful.

ScreenshotsCopy Anchor Link

The panel as it opens.

The constructor tab.

The grammars tab.

The parts bin tab.

RelatedCopy Anchor Link

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