Skip to content

Introduce the ability to define objective plate designs - #17

Open
marpaia wants to merge 9 commits into
masterfrom
plates
Open

marpaia wants to merge 9 commits into
masterfrom
plates

Conversation

@marpaia

@marpaia marpaia commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Describe a plate by what each well must contain at the end, and let the compiler decide how to pipette it.

Example

from lab import Protocol, compile, uL, uM
from lab.plates import PlateDesign, Settings, Stock, assemble, find_serial_dilutions, parallelize, well_target
from lab.units import units

ug_mL = units("ug/mL")

# The plate as an outcome: a material and the final concentration of each solute, per well.
# Rows A and B hold two plasmids across an 8-step 2-fold Van series at constant Sal and TMP.
design = PlateDesign.build(
    "cultures",
    final_volume=200 * uL,
    wells=[
        well_target(
            f"{row}{column}",
            material=plasmid,
            concentrations={"Van": 100 / 2 ** (12 - column) * uM, "Sal": 10 * uM, "TMP": 3 * ug_mL},
        )
        for row, plasmid in (("A", "plasmid-1"), ("B", "plasmid-2"))
        for column in range(5, 13)
    ],
)
(gradient,) = parallelize(find_serial_dilutions(design, "Van"))
assert (gradient.steps, gradient.width) == (8, 2)  # one series, in lanes A and B

p = Protocol("cultures")
plate = p.plate("cultures", capacity=360 * uL)
reagents = p.plate("reagents", shape=(1, 12), capacity=15000 * uL, dead_volume=500 * uL)
medium = p.container("medium", contents="medium", volume=15000 * uL, capacity=15000 * uL)
waste = p.container("waste", capacity=15000 * uL)
for well, name in (("A1", "Van 1000 uM"), ("A2", "Sal 100 uM"), ("A3", "TMP 300 ug/mL"), ("A4", "plasmid-1"), ("A5", "plasmid-2")):
    p.load(reagents[well], name, volume=15000 * uL)

# assemble() decides how to pipette it: the Van series becomes a serial dilution built
# well to well, Sal and TMP are dosed directly, and every well ends at 200 µL.
report = assemble(
    p,
    design,
    plate=plate,
    stocks=[
        Stock(solute="Van", concentration=1000 * uM, source=reagents["A1"]),
        Stock(solute="Sal", concentration=100 * uM, source=reagents["A2"]),
        Stock(solute="TMP", concentration=300 * ug_mL, source=reagents["A3"]),
    ],
    medium=medium,
    inocula={"plasmid-1": reagents["A4"], "plasmid-2": reagents["A5"]},
    waste=waste,
    settings=Settings(final_volume=200 * uL, inoculum_volume=10 * uL),
)
bundle = compile(p, to=None, warn_below=2 * uL)
# report.gradients: one 8-step serial dilution in two lanes; 38 operations; no advisories.

Plate designs (lab.plates)

  • PlateDesign / WellTarget: a Material and the final concentration of every solute, per well. No steps. A material is a name, or a strain and construct that name it (Material(strain="BL21", construct="pA") is called BL21 / pA), with an optional SBOL design IRI. A bare name is accepted anywhere a material is; nothing in it is parsed.
  • Three ways to get one: build it well by well, lay it out from Requirements with arrange() (materials × conditions × a dilution series, plus controls), or read it back from any design with infer_requirements().
  • find_serial_dilutions() detects geometric gradients whose other conditions are constant (tolerant of float-rounded sheet values); parallelize() merges rows into multichannel lanes; find_replicate_groups() finds identical chemistry.
  • plan_serial_dilution() / record_serial_dilution() build a gradient well to well at a concentrate factor so the peak volume fits the well; plan_premix() / record_premix() prepare replicate portions once.
  • assemble() prepares a design from declared stocks, medium, vehicle, and inocula under Strategy.DIRECT, SERIAL, or AUTO, and reports what it decided.
  • The LMSF CSV lives in lab.plugins.lmsf as a view over PlateDesign; core has no knowledge of it. The plugin builds materials from the sheet's strain and plasmid columns and reads them back from those attributes. The concentration-series example runs on assemble() and prepares its Van gradients serially by default (--strategy switches).

Advisories and pipetting limits

  • compile(..., warn_below=, resolution=) records Diagnostics on the Compilation, in plan.json, and in a worksheet Advisories section for steps below a head's trusted floor or the lab's own minimum. Hard limits stay CompileErrors.
  • lab.limits.PipettingLimits describes each head's range and trusted floor; every TargetPlan lists its heads; Manual(pipettes=...) takes a bench set; advise_design() gives the same advice before any protocol exists.

Multichannel lanes and tip policy

  • p.transfer(plate.column(12), plate.column(11), ...) and p.mix(...) on sequences record MultiTransfer / MultiMix lane sets. Opentrons 8-channel heads run a full column in one stroke, STAR layouts take up to eight Channels, single-channel heads run lanes in turn, and the worksheet animates them together.
  • TipPolicy is recorded with the protocol or overridden at compile time: fresh per step, reuse per source, or reuse while every destination's contents are contained in the source's (with prewet() for the pre-wetting stroke). Targets pick up and drop tips at the numbered boundaries; lab.tips numbers and counts them.

Also

  • Protocol.capacity(), lab.uM / lab.mM, lab.config.PlateDesignConfig / PreparationConfig.
  • Docs: docs/plates.md plus updates to the configuration and worksheet pages; CHANGELOG under Unreleased.
  • 349 tests, including OT-2 simulation and STAR Chatterbox runs for the lane sets and tip policies.

Describe a plate by its intended end state (PlateDesign), detect
geometric gradients and replicate groups, plan and record serial
dilutions at a concentrate factor, premix replicate portions, arrange a
plate from requirements, and assemble a design from declared sources
under a direct, serial, or automatic strategy. The LMSF destination CSV
is read and written by lab.plugins.lmsf as a view of a design. The
concentration-series example runs on these functions and prepares the
layout's Van gradients serially by default.
Each target reports its heads as PipettingLimits; compile() compares
every liquid step with the smallest covering head's trusted floor or the
lab's warn_below and records Diagnostics on the Compilation, in
plan.json, and in a worksheet Advisories section. advise_design() gives
the same advice for a plate design before any protocol exists.
Protocol.transfer() and mix() accept sequences of wells and record
MultiTransfer and MultiMix lane sets. Opentrons 8-channel heads run a
full-column lane set in one stroke, STAR layouts configure up to eight
channels and run lanes across them, and single-channel heads run lanes
in turn. A TipPolicy recorded with the protocol (or overridden at
compile time) decides when targets replace tips, including David Ross's
containment rule with a pre-wetting stroke; lab.tips numbers and counts
tips for the targets and the worksheet. Serial dilution levels are
recorded as lane sets and the example's STAR layout has eight channels.
infer_requirements() reads materials, the longest gradient, the
constant conditions along it, every other well as a control, and the
lane count off a design, and reports whether arranging them reproduces
the plate exactly. Concentrations in advice and labels show in bench
units.
ConditionSpec.steps and include_zero shorten or extend the plate's
gradient for one condition, so a layout whose row pairs carry 8- and
5-step series counts and arranges as it is laid out. infer_requirements
reads them off each gradient and notes when control placement differs.
A Material carries a display name plus optional strain, construct, and
SBOL design IRI. Well targets and requirements reference the record,
well_target and Requirements accept bare names, and a design rejects two
different records under one name. The LMSF plugin builds its materials
from the sheet's strain and plasmid columns and reads them back from
those attributes instead of parsing the name.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant