iGGA: a barcoded combinatorial library¶

Iterative Golden Gate appends one list of parts a round, so a few dozen proteins become thousands of plasmids. Each part carries an 11 bp barcode at its junction, so sequencing a member says which protein sits at every position. One command designs the synthesis order, draws the barcodes, simulates the rounds, sizes the colonies each round needs and writes the bench protocol.

When to use it¶

• Two or more lists of protein or DNA parts, and you want every combination as a plasmid.
• You want a member read back from sequencing alone, with nothing to look up.
• The library is too large to build member by member.

Use Golden Gate assembly for one defined construct instead, and DMX to read picked wells back.

What you need¶

One file. It names a FASTA of the parts, the vector the first round opens, the backbone the library ends in, and this run's own numbers. A project is the chain of protocols; a build is one run's choices, and the file holding a build is called project.json. The run below uses files that ship with the repo. Copy them to start one of your own.

Run it¶

pixi run synbio igga plan docs/examples/ap1-library/project.json --out library/ \
  --working-site EGFP --prices docs/examples/ap1-library/prices.csv

--working-site says where the ccdB cassette goes in a backbone carrying none; --prices points at the price list this lab holds. The run states its design in one line, then every file:

AP-1 DESynR round 3: 6435 bp, 72 parts in 3 lists, 13,824 constructs, 3 rounds, entry overhangs AGGA, AGAT, GCAT, scar TTCC, 27 amino acid changes, checks pass
library/parts.tsv
library/barcodes.tsv
library/changes.tsv
library/round-1.dna
library/round-2.dna
library/product.dna
library/block-vector-1.dna
library/block-vector-2.dna
library/block-vector-3.dna
library/working-vector-ccdb.dna
library/protocol/project.json
library/protocol/index.html
library/protocol/01-part-carrier.html
library/protocol/02-primer-plates.html
library/protocol/03-cargo-ordering-and-pool-preparation.html
library/protocol/04-cargo-creation.html
library/protocol/05-cargo-validation-barcode-ligation.html
library/protocol/05-cargo-validation-index-pcr.html
library/protocol/06-library-assembly-in-rounds.html
library/protocol/07-final-cargo-ligation.html
library/protocol/reagents.html
library/protocol/references.html
library/pool.tsv
library/pool-primers.tsv
library/oligo.dna
library/library-read-primers.tsv

Read that line first. 72 parts in three lists make 13,824 constructs. Each list enters on its own overhang and every part leaves the same TTCC scar. The planner picked that set because it costs the proteins fewest residues: the 27 changes in changes.tsv are what you pay for it.

A round opens the library with BbsI and releases one part list with BsaI, in separate tubes, then ligates, electroporates and preps the result as the next round's destination. A 34 bp internal stuffer is kept each round, which is what lets the next round open the product; a capping block ends the chain instead. The 41 bp barcode block reads in reverse of the round order.

The last round needs 195,386 colonies for a 0.99 chance that none of its 13,824 products is missing, 14 times its products. That is library coverage: colonies against distinct products, not sequencing depth. A round below its floor loses members no later round puts back.

The run ends by moving the library into a working vector, where an application gets it. The plan reads that backbone's cargo enzyme first, then keeps every block clear of it: an enzyme a block spells cannot be the one that admits the library.

What it wrote¶

Each name links to what that run wrote, published here unedited. Nothing is typed by hand, so the same inputs always write the same bytes. Change the build and run the command again to change the design. To change what a page says, edit the chain's own data file and render it again:

pixi run mbio protocol render library/protocol/project.json

Figures, drawn by mbio plot map:

What the bench works through¶

The run is not one sitting. The protocol/ folder holds a page for each, in order.

Reading every well back has a page for each route, and the bench does one, never both; DMX covers that job. The way in draws the chain, lists the checks, names every number with no source, and schedules the run: 49 steps, 19 of which hold the bench. Each page names the one before and after it, so you can mail one to whoever runs that sitting.

Before you order¶

• Read the way in, then every page of the chain.
• Replace this build's numbers with yours: completeness, barcode rules, linkage fidelity and final assembly.
• Decide that each residue change in changes.tsv is harmless in your proteins.
• Check each round's colony floor against the cells and cuvettes you hold.
• Re-price every row against your own vendors; a band here is a price band, not a gel band.

Tips and troubleshooting¶

Your backbone carries Type IIS sites. The working vector here is not the file Addgene sends. Addgene 171123 reads six BsaI and two BsmBI sites and a round would cut every one, so all eight came out first. Two sit in TAR, the stem-loop at each end of the viral genome, which has to fold to work: removing a site there changes a shape the virus needs. Whether it still packages is open — the one published backbone carrying that change reports no titre. Measure it.

A round comes up short of colonies. Plate a dilution of every round beside a no-donor control, and subtract the control. The round's page does that sum for you: type both counts and the dilution into its expected result and it says whether the net clears the floor. Run the round again rather than carrying on: members lost in one round are missing from all of them after it.

A part's protein comes back changed. A junction spells whole codons, so the overhang decides the residues either side of it. The planner scores every candidate set across all the parts and keeps the cheapest, so a change in changes.tsv is one no other set avoided.

Where the numbers come from¶

This run's settings are one build's answers, not the method's defaults: its completeness, its barcode rules, its linkage fidelity of 0.9, and the 75 ng of working vector its last tube takes. The build states no cargo mass, because cargo is never pipetted — the whole release goes in, so the digest fixes how much meets the vector. The pages label each of those as this run's own figure. Copy the file without replacing them and you carry someone else's settings.

Volumes, units, times and temperatures are cited step by step inside each page, and references.html lists every document the run cites. Where nothing publishes a number the page prints a hole, not a guess: 35 here, four at the bench and 31 prices, since this lab priced nine of the bill's 40 rows. Round fidelity is measured ligation data — see how fidelity is predicted. A barcode names a library part here, where a barcode-kit member marks a well; barcode sets says how a set is drawn.

pixi run synbio igga plan --help lists the rest: what the parts FASTA holds, where a stuffer or cassette goes, how a record name is matched to a position, and reading a ligase matrix you hold.

References¶