From ef5ef0005db68662e6cb5b85d3509bc06b562149 Mon Sep 17 00:00:00 2001 From: Mike Arpaia Date: Thu, 5 Nov 2026 23:17:26 +0000 Subject: [PATCH 1/9] Add lab.plates designs, gradient detection, and serial dilution 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. --- CHANGELOG.md | 12 + README.md | 2 +- docs/configuration.md | 4 + docs/plates.md | 206 ++++++++++ examples/concentration_series/__main__.py | 62 ++- examples/concentration_series/config.toml | 27 +- examples/concentration_series/inputs.py | 237 +++++------ examples/concentration_series/protocol.py | 174 ++------ src/lab/__init__.py | 4 +- src/lab/config.py | 42 ++ src/lab/plates/__init__.py | 63 +++ src/lab/plates/arrange.py | 190 +++++++++ src/lab/plates/design.py | 200 +++++++++ src/lab/plates/dilution.py | 128 ++++++ src/lab/plates/patterns.py | 268 ++++++++++++ src/lab/plates/premix.py | 86 ++++ src/lab/plates/recipe.py | 371 +++++++++++++++++ src/lab/plugins/__init__.py | 5 + src/lab/plugins/lmsf/__init__.py | 23 ++ src/lab/plugins/lmsf/layout.py | 163 ++++++++ src/lab/protocol.py | 14 +- src/lab/units.py | 2 + tests/test_concentration_series.py | 258 +++++++----- tests/test_lmsf_plugin.py | 103 +++++ tests/test_plates.py | 478 ++++++++++++++++++++++ 25 files changed, 2734 insertions(+), 388 deletions(-) create mode 100644 docs/plates.md create mode 100644 src/lab/plates/__init__.py create mode 100644 src/lab/plates/arrange.py create mode 100644 src/lab/plates/design.py create mode 100644 src/lab/plates/dilution.py create mode 100644 src/lab/plates/patterns.py create mode 100644 src/lab/plates/premix.py create mode 100644 src/lab/plates/recipe.py create mode 100644 src/lab/plugins/__init__.py create mode 100644 src/lab/plugins/lmsf/__init__.py create mode 100644 src/lab/plugins/lmsf/layout.py create mode 100644 tests/test_lmsf_plugin.py create mode 100644 tests/test_plates.py diff --git a/CHANGELOG.md b/CHANGELOG.md index fca1c70..6dc97c1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## Unreleased + +### Added + +- `lab.plates` describes a plate by its intended end state. `PlateDesign` and `WellTarget` hold per-well materials and solute concentrations; `find_serial_dilutions()` and `parallelize()` detect geometric gradients, `find_replicate_groups()` identical chemistry; `plan_serial_dilution()` and `record_serial_dilution()` build a gradient at a chosen concentrate factor with the arithmetic documented in `docs/plates.md`; `plan_premix()` and `record_premix()` prepare replicate portions once; `arrange()` lays out a plate from `Requirements`; `assemble()` prepares a design from declared stocks, medium, vehicle, and inocula under a `Strategy` of direct, serial, or automatic dosing and reports its decisions. +- `lab.config.PlateDesignConfig` and `PreparationConfig` are the typed JSON and TOML forms of a design and of the preparation settings. `lab.plugins.lmsf` reads and writes the LMSF destination CSV as a view of a design; the core package does not depend on that format. +- `Protocol.capacity()` returns the declared capacity of a plate or well. `lab.uM` and `lab.mM` are exported molar units. + +### Changed behavior + +- The concentration-series example prepares the layout's Van gradients as serial dilutions by default (`preparation.strategy = "auto"`), draws gradient diluent from a second medium reservoir well, and discards one transfer volume per lane into a declared waste container. `--strategy direct` reproduces per-well dosing. Its configuration gains a `[preparation]` table, `medium.diluent_volume`, a `waste` container, and one more tip rack per robot layout. + ## 0.3.0 ### Changed behavior diff --git a/README.md b/README.md index 3945f03..f3ba388 100644 --- a/README.md +++ b/README.md @@ -198,7 +198,7 @@ Liquid-class cards plot flow rate against time for the selected operation. Aspir Preparation proceeds across the plate: medium first, then vehicle and each stock, followed by inoculation and mixing. Equal doses from the same source share a `distribute()` operation and one tip. Unique doses remain individual transfers. Preparing the full supplied layout requires 327 tips, including source resuspension and destination mixing. The worksheet reports the tip count alongside the operation count. -The standalone [concentration-series example](examples/concentration_series/) reads a [plate layout](examples/concentration_series/layout.csv) and [protocol configuration](examples/concentration_series/config.toml), then records ordinary transfers and mixes. The supplied layout preserves the well coordinates and target concentrations of an LMSF fitness export, with generic strain and plasmid names. Every CSV row is prepared by default: 96 wells covering 24 conditions for each of four plasmid samples. An optional `wells` list in the configuration selects a subset explicitly. `lab.units.dilution_volume()` calculates stock volumes; the recipe balances vehicle and medium, inoculates, and mixes. Source identities and volumes, working-stock selection, and liquid classes are explicit. The TOML also declares development OT-2 and STAR deck layouts, parsed directly into Lab's existing `Deck` types, with reservoir sources and enough tips for the full plate. +The standalone [concentration-series example](examples/concentration_series/) reads a [plate layout](examples/concentration_series/layout.csv) and [protocol configuration](examples/concentration_series/config.toml), then records ordinary transfers and mixes. The supplied layout preserves the well coordinates and target concentrations of an LMSF fitness export, with generic strain and plasmid names. Every CSV row is prepared by default: 96 wells covering 24 conditions for each of four plasmid samples. An optional `wells` list in the configuration selects a subset explicitly. `lab.plugins.lmsf` reads the CSV into a `lab.plates.PlateDesign`, and `lab.plates.assemble()` plans every well: the two Van gradients are detected and prepared as serial dilutions (`--strategy auto`, the default) or dosed directly (`--strategy direct`), the recipe balances vehicle and medium, inoculates, and mixes. Source identities and volumes, working-stock selection, and liquid classes are explicit. [Plate designs](docs/plates.md) documents the design model, pattern detection, and the dilution arithmetic. The TOML also declares development OT-2 and STAR deck layouts, parsed directly into Lab's existing `Deck` types, with reservoir sources and enough tips for the full plate. `main()` parses the TOML into `ProtocolConfig` and the CSV into `PlateLayout` using Pydantic. The reusable quantity fields and liquid-class schemas come from [`lab.config`](docs/configuration.md), available through `lab-compiler[config]` and included in development dependencies (`uv sync --locked`). `prepare_wells()` checks the inputs together and calculates doses; `protocol()` consumes those prepared wells and the validated configuration to record operations. The configuration mirrors the TOML: `medium.name` is `config.medium.name`, and liquid-class names remain names until protocol construction resolves them. Saved configuration comes from that same model. diff --git a/docs/configuration.md b/docs/configuration.md index 2549aa9..c825b06 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -45,3 +45,7 @@ Quantity fields accept unit-bearing strings or Pint `Quantity` objects. They rej Existing Lab dataclasses can also be fields. For example, `deck: lab.deck.Deck` parses nested containers and layouts into typed Lab objects, including enums, locations, and Decimal limits. Pydantic applies their existing dataclass validation. The [concentration-series configuration](../examples/concentration_series/config.toml) demonstrates this without a separate deck parser or schema. For applications that do not use Pydantic, `lab.units.parse_quantity(value, unit="microliter")` provides the same normalization. `unit` may also be a tuple of alternatives for different dimensions, such as `("mole/liter", "gram/liter")`. The first compatible unit is used. `positive=False` permits zero; negative or nonfinite values always fail. This input parser does not change the `Protocol` API: operations take quantity objects. + +## Plate designs and preparation settings + +`PlateDesignConfig` is the typed form of a [`lab.plates.PlateDesign`](plates.md): a name, an optional shape, the final volume, and `wells`, each with an optional `material` and a `concentrations` table of unit-bearing strings. `to_design()` builds the Lab object. `PreparationConfig` carries the `strategy` (`direct`, `serial`, or `auto`), `concentrate`, `serial_min_steps`, and the optional premix settings that `lab.plates.Settings` consumes. The concentration-series configuration uses `PreparationConfig` as its `[preparation]` table. diff --git a/docs/plates.md b/docs/plates.md new file mode 100644 index 0000000..226e0f7 --- /dev/null +++ b/docs/plates.md @@ -0,0 +1,206 @@ +# Plate designs + +`lab.plates` describes a plate by its intended end state and turns that description into +recorded operations. A `PlateDesign` lists, for each well, an optional material and the final +concentration of every solute. It records no steps. Three ways lead to a design: + +| Entry point | Code | Use | +| --- | --- | --- | +| Explicit layout | `PlateDesign.build(name, final_volume=..., wells=[well_target("A1", ...), ...])` or a format plugin such as `lab.plugins.lmsf.read_layout` | A sheet or script that names every well | +| Requirements | `arrange(Requirements(materials=..., conditions=..., gradient=..., controls=...))` | "Four plasmids, two Sal levels, an 8-step 2-fold Van series, blanks"; the plate is laid out for you | +| Procedure | `Protocol` operations directly | Anything the two descriptions above cannot express | + +`assemble()` prepares a design from declared sources and reports what it decided. The example +in [`examples/concentration_series/`](../examples/concentration_series/) is a thin command-line +wrapper around these functions. + +## Designs + +```python +from lab import uL, uM +from lab.plates import PlateDesign, well_target +from lab.units import units + +ug_ml = units("ug/mL") +design = PlateDesign.build( + "cultures", + final_volume=200 * uL, + wells=[ + well_target( + f"A{column}", + material="strain / plasmid-1", + concentrations={"Van": van * uM, "Sal": 10 * uM, "TMP": 3 * ug_ml}, + ) + for column, van in zip(range(12, 4, -1), (100, 50, 25, 12.5, 6.25, 3.125, 1.5625, 0.78125)) + ], +) +design["A12"].concentration("Van").quantity # 0.0001 mole / liter +design.row("A") # WellTarget records in column order +design.solutes # ('Sal', 'TMP', 'Van') +``` + +Concentrations are normalized to Decimal `mole/liter` or `gram/liter`, the dimensions +`lab.units.dilution_volume()` accepts; the two are never converted into each other. A target of +zero is kept because it marks an intended absence, for example a gradient's zero control. The +material is free text; a plugin such as `lab.plugins.lmsf` gives it a convention +(`"strain / plasmid"`). `lab.config.PlateDesignConfig` is the typed JSON or TOML form of a design +for applications installed with `lab-compiler[config]`. + +## Patterns in a design + +Two preparation patterns cover the layouts in use: direct dosing from a stock, and serial +dilution along a geometric gradient. `find_serial_dilutions(design, solute)` finds runs of +wells, adjacent along a row or column, whose concentrations of one solute descend by a constant +fold while the material and every other solute stay constant. Ratios are compared with a +relative tolerance so float-rounded sheet values such as `14.2857142857143` still form a 2-fold +series. A trailing well with the solute at zero in the same context is attached as the zero +control. `axis="set"` ignores position and groups scattered wells by concentration instead. + +`parallelize()` merges row candidates that share the solute, fold, top, and column path into one +candidate whose levels are plate columns: what an 8-channel head or several independent STAR +channels move in one stroke. `find_replicate_groups()` lists wells with identical chemistry, +ignoring the material, for premixing. + +```python +from lab.plates import find_serial_dilutions, parallelize + +(gradient,) = parallelize(find_serial_dilutions(design, "Van")) +gradient.levels[0] # ('A12',) ... or ('A12', 'C12', 'E12', 'G12') across four rows +gradient.fold, gradient.steps, gradient.zero_wells +``` + +## Serial dilution arithmetic + +Every well below the top is pre-filled with the gradient volume `G` of diluent. Moving `t` from +a well at concentration `c` into `G` gives `c·t/(G+t)`; requiring `c/f` gives `t = G/(f−1)`. +Each well ends at `G`, the top is prepared at `G + t`, and the bottom level passes its surplus +`t` to waste. The peak `G + t = G·f/(f−1)` must fit the well, which is why folds below 2 are +rejected: a 1.5-fold series needs three times the gradient volume in one well. + +`plan_serial_dilution()` sizes a gradient at `concentrate` times the final concentration in +`G = V/concentrate`. The constant additions made afterwards (co-solutes, vehicle, medium, +inoculum) bring every well to `V` and dilute the gradient solute by exactly `concentrate`. The +top stock dose is independent of that factor: `d0 = c0·V·f / (cs·(f−1))`. + +| V = 200 µL, f = 2, stock 1000 µM, top 100 µM, 360 µL wells | concentrate 1 | concentrate 2 | +| --- | --- | --- | +| G | 200 | 100 | +| t | 200 | 100 | +| peak G + t | 400 (rejected: exceeds 360) | 200 | +| stock into the top well | 40 | 40 | +| diluent into the top well | 360 | 160 | +| diluent into every other well | 200 | 100 | +| smallest pipetted volume | 40 | 40 (direct dosing of 0.78125 µM needs 0.15625 µL) | + +The gradient diluent is plain medium; co-solutes are dosed afterwards by the direct method, so +the transferred volume carries only medium and the gradient solute. A stock with a nonzero +vehicle fraction cannot feed a gradient, because the vehicle would dilute along the chain; such +solutes are dosed directly. `record_serial_dilution()` records the diluent fills, the top doses, +and one mix-then-transfer pair per step and lane, ending with a transfer to waste. + +```python +from decimal import Decimal +from lab import Protocol, uL, uM +from lab.plates import plan_serial_dilution, record_serial_dilution + +p = Protocol("gradient") +plate = p.plate("cultures", capacity=360 * uL) +stock = p.container("van", contents="Van 1000 uM", volume=1000 * uL, capacity=1500 * uL) +medium = p.container("medium", contents="medium", volume=15000 * uL, capacity=15000 * uL) +waste = p.container("waste", capacity=15000 * uL) +plan = plan_serial_dilution( + gradient, + stock_concentration=1000 * uM, + final_volume=200 * uL, + capacity=p.capacity(plate), + reserved=10 * uL, # inoculum added later + concentrate=Decimal(2), +) +record_serial_dilution(p, plan, plate=plate, stock=stock, diluent=medium, waste=waste) +``` + +## Premixes + +`find_replicate_groups()` with `plan_premix()` and `record_premix()` prepares the shared portion +of replicate wells once in a tube, then distributes one portion per well. Components are pipetted +at `n × overage` times their per-well dose, so a 2 µL selector dose for four replicates becomes +one 8.8 µL move at the default 1.1 overage. Premixing needs tubes or reservoir wells on the deck; +`assemble()` uses it only when `Settings.premix_min_group` is set and `tubes` are supplied. + +## Requirements + +```python +from decimal import Decimal +from lab.plates import ConditionSpec, ControlSpec, GradientSpec, Requirements, arrange + +requirements = Requirements( + name="cultures", + final_volume=200 * uL, + materials=("strain / p1", "strain / p2", "strain / p3", "strain / p4"), + conditions=( + ConditionSpec(label="Sal 10", concentrations={"Sal": 10 * uM, "TMP": 3 * ug_ml}), + ConditionSpec(label="Sal 25", concentrations={"Sal": 25 * uM, "TMP": 3 * ug_ml}), + ), + gradient=GradientSpec(solute="Van", top=100 * uM, fold=Decimal(2), steps=8), + controls=(ControlSpec(label="unselected", concentrations={"Van": 0 * uM, "Sal": 0 * uM}),), +) +requirements.well_count # 68 of 96 +arrangement = arrange(requirements) +arrangement.design # series along rows, highest concentration in column 12 +arrangement.unused_wells +``` + +`arrange()` raises with the overflow when the plate is too small, so a design tool can show +"over by N wells" instead of a partial layout. One gradient per plate is supported; a second +gradient in the other direction needs an intermediate plate. + +## Assembling a design + +```python +from lab.plates import Settings, Stock, Strategy, assemble + +report = assemble( + p, + design, + plate=plate, + stocks=[Stock(solute="Van", concentration=1000 * uM, source=van, max_target=200 * uM), ...], + medium=medium, + diluent=second_medium_well, # optional; gradients draw from here + inocula={"strain / plasmid-1": culture_1, ...}, + vehicle=dmso, + waste=waste, + settings=Settings( + final_volume=200 * uL, + inoculum_volume=10 * uL, + vehicle_fraction=Decimal("0.02"), + strategy=Strategy.AUTO, + concentrate=Decimal(2), + serial_min_steps=4, + ), +) +report.gradients # SerialDilutionPlan per gradient actually recorded +report.skipped_gradients # (candidate, reason) pairs AUTO left to direct dosing +report.wells # per-well doses, gradient volume, vehicle, medium, inoculum +``` + +`Strategy.DIRECT` doses every well from its stocks. `Strategy.SERIAL` requires every detected +gradient of at least `serial_min_steps` levels to be feasible. `Strategy.AUTO` uses a serial +dilution where it is detected and fits, and doses directly elsewhere. Stocks are selected per +target as the least concentrated stock whose `max_target` covers it. The recipe balances the +vehicle fraction against vehicle carried by stocks, fills the remainder with medium, then +inoculates and mixes. Every balance is checked; a negative one is a `ValueError` naming the well. + +## Format plugins + +Sheet formats are not core concepts. `lab.plugins.lmsf` reads and writes the LMSF destination +CSV as a view of a `PlateDesign`: + +```python +from lab.plugins.lmsf import read_layout, write_layout + +design = read_layout(Path("layout.csv").read_text(), name="cultures", final_volume=200 * uL) +text = write_layout(design, solute_order=("Van", "Sal", "TMP")) +``` + +Other formats follow the same shape: a row model, a reader that yields a design, and a writer +that requires whatever the format needs. diff --git a/examples/concentration_series/__main__.py b/examples/concentration_series/__main__.py index 21a0383..ff6b62e 100644 --- a/examples/concentration_series/__main__.py +++ b/examples/concentration_series/__main__.py @@ -2,25 +2,35 @@ Run with --csv and --config (see config.toml). Stocks are supplied already prepared. Every CSV row is prepared unless config.wells selects a subset. -The example ends with an inoculated culture plate. +--strategy chooses direct dosing, serial dilution of detected gradients, or +automatic selection. The example ends with an inoculated culture plate. """ import argparse -import csv import hashlib import tomllib -from io import StringIO from pathlib import Path -from examples.concentration_series.inputs import ( - Condition, - PlateLayout, - ProtocolConfig, - prepare_wells, -) +from examples.concentration_series.inputs import ProtocolConfig from examples.concentration_series.protocol import protocol from lab import compile from lab.equipment import LiquidHandler +from lab.plates import PlateDesign +from lab.plugins.lmsf import read_layout + + +def select(design: PlateDesign, wells: tuple[str, ...] | None) -> PlateDesign: + """Keep the configured subset of wells, in the requested order.""" + if wells is None: + return design + if missing := set(wells) - {target.well for target in design.wells}: + raise ValueError(f"Selected wells absent from CSV: {sorted(missing)}") + return PlateDesign( + name=design.name, + shape=design.shape, + final_volume_ul=design.final_volume_ul, + wells=tuple(design[well] for well in wells), + ) def main() -> None: @@ -28,26 +38,38 @@ def main() -> None: parser.add_argument("--csv", required=True, type=Path, help="LMSF fitness destination CSV") parser.add_argument("--config", required=True, type=Path, help="Protocol configuration TOML") parser.add_argument("--target", choices=("manual", "ot2", "star"), default="manual") + parser.add_argument( + "--strategy", + choices=("direct", "serial", "auto"), + help="Override preparation.strategy from the configuration", + ) parser.add_argument("--out") args = parser.parse_args() try: with args.config.open("rb") as stream: - config = ProtocolConfig.model_validate(tomllib.load(stream)) + raw = tomllib.load(stream) + if args.strategy is not None: + raw.setdefault("preparation", {})["strategy"] = args.strategy + config = ProtocolConfig.model_validate(raw) csv_bytes = args.csv.read_bytes() - reader = csv.DictReader(StringIO(csv_bytes.decode("utf-8-sig"), newline="")) - headers = {field.alias or name for name, field in Condition.model_fields.items()} - if set(reader.fieldnames or ()) != headers or len(reader.fieldnames or ()) != len(headers): - raise ValueError( - "Expected the LMSF fitness CSV schema; cytometry needs a separate recipe" - ) - layout = PlateLayout.model_validate({"conditions": list(reader)}) - prepared_wells = prepare_wells(layout, config) - p = protocol(prepared_wells, config) + design = select( + read_layout( + csv_bytes.decode("utf-8-sig"), name="cultures", final_volume=config.final_volume + ), + config.wells, + ) + p, report = protocol(design, config) summary, _, notes = p.description.partition("\n\n") + gradients = ", ".join( + f"{plan.candidate.solute} {plan.candidate.steps}-step {plan.candidate.fold}-fold " + f"across {plan.candidate.width} rows" + for plan in report.gradients + ) p.description = ( f"{summary}\n\n" f"Targets from {args.csv.name} (SHA256 {hashlib.sha256(csv_bytes).hexdigest()}).\n\n" - f"{notes}" + + (f"Serial dilutions: {gradients}.\n\n" if gradients else "") + + notes ) handler = None if args.target == "manual" else LiquidHandler(args.target) bundle = compile( diff --git a/examples/concentration_series/config.toml b/examples/concentration_series/config.toml index 1bf54d5..b1b6b24 100644 --- a/examples/concentration_series/config.toml +++ b/examples/concentration_series/config.toml @@ -13,6 +13,16 @@ source_dead_volume = "500 uL" # Assert known absence of every CSV solute and DMSO from medium AND all cultures. solute_and_vehicle_free_medium_and_cultures = true +# Gradients the CSV contains (geometric series of one solute with everything else +# constant) are prepared as serial dilutions under "auto" or "serial"; "direct" doses +# every well straight from its stock. The gradient is built at `concentrate` times the +# final concentration so the mixing volume fits the well, then topped up with the +# constant additions. Runs shorter than serial_min_steps are dosed directly. +[preparation] +strategy = "auto" +concentrate = "2" +serial_min_steps = 4 + # Portable classes specify these two rates only. Other robot settings and # calibration retain SDK defaults; the numbers below need instrument validation. [liquid_classes.aqueous] @@ -41,6 +51,7 @@ name = "Base medium (development input)" well = "A1" # medium reservoir; other sources use reagents volume = "15000 uL" dead_volume = "500 uL" +diluent_volume = "10000 uL" # loads A2 of the same reservoir for serial dilutions liquid_class = "aqueous" [vehicle] @@ -138,6 +149,10 @@ labware = { kind = "plate", rows = 8, columns = 12, capacity_ul = "360" } [[deck.containers]] id = "medium" +labware = { kind = "reservoir", rows = 1, columns = 2, capacity_ul = "15000" } + +[[deck.containers]] +id = "waste" labware = { kind = "reservoir", rows = 1, columns = 1, capacity_ul = "15000" } [[deck.layouts]] @@ -145,7 +160,8 @@ liquid_handler = "ot2" placements = [ { container = "reagents", model = "nest_12_reservoir_15_ml", location = { name = "1" } }, { container = "cultures", model = "corning_96_360_ul", location = { name = "2" } }, - { container = "medium", model = "nest_12_reservoir_15_ml", location = { name = "3" }, wells = ["A1"] }, + { container = "medium", model = "nest_12_reservoir_15_ml", location = { name = "3" }, wells = ["A1", "A2"] }, + { container = "waste", model = "nest_12_reservoir_15_ml", location = { name = "4" }, wells = ["A12"] }, ] tip_racks = [ { id = "p300_tips", model = "opentrons_300_ul", location = { name = "5" } }, @@ -153,9 +169,10 @@ tip_racks = [ { id = "p300_tips_2", model = "opentrons_300_ul", location = { name = "7" } }, { id = "p300_tips_3", model = "opentrons_300_ul", location = { name = "8" } }, { id = "p20_tips_2", model = "opentrons_20_ul", location = { name = "9" } }, + { id = "p300_tips_4", model = "opentrons_300_ul", location = { name = "10" } }, ] pipettes = [ - { model = "p300_single_gen2", mount = "left", tip_racks = ["p300_tips", "p300_tips_2", "p300_tips_3"] }, + { model = "p300_single_gen2", mount = "left", tip_racks = ["p300_tips", "p300_tips_2", "p300_tips_3", "p300_tips_4"] }, { model = "p20_single_gen2", mount = "right", tip_racks = ["p20_tips", "p20_tips_2"] }, ] @@ -164,7 +181,8 @@ liquid_handler = "star" placements = [ { container = "reagents", model = "nest_12_reservoir_15_ml", location = { holder = "plates", index = 0 } }, { container = "cultures", model = "corning_96_360_ul", location = { holder = "plates", index = 1 } }, - { container = "medium", model = "nest_12_reservoir_15_ml", location = { holder = "plates", index = 2 }, wells = ["A1"] }, + { container = "medium", model = "nest_12_reservoir_15_ml", location = { holder = "plates", index = 2 }, wells = ["A1", "A2"] }, + { container = "waste", model = "nest_12_reservoir_15_ml", location = { holder = "plates", index = 3 }, wells = ["A12"] }, ] carriers = [ { id = "plates", model = "hamilton_plate_5", location = { index = 15 } }, @@ -175,9 +193,10 @@ tip_racks = [ { id = "star_tips_2", model = "hamilton_300_ul", location = { holder = "tips", index = 1 } }, { id = "star_tips_3", model = "hamilton_300_ul", location = { holder = "tips", index = 2 } }, { id = "star_tips_4", model = "hamilton_300_ul", location = { holder = "tips", index = 3 } }, + { id = "star_tips_5", model = "hamilton_300_ul", location = { holder = "tips", index = 4 } }, ] # One channel and 300 uL tips. The 1 uL minimum is a software demonstration # limit, not a validated physical operating range. channels = [ - { index = 0, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4"] }, + { index = 0, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, ] diff --git a/examples/concentration_series/inputs.py b/examples/concentration_series/inputs.py index 7d39095..ef82e94 100644 --- a/examples/concentration_series/inputs.py +++ b/examples/concentration_series/inputs.py @@ -1,7 +1,8 @@ -"""LMSF fitness CSV and protocol configuration models, followed by dose calculation. +"""Protocol configuration for preparing an LMSF destination layout. -The models mirror the CSV columns and config.toml. prepare_wells() checks the -inputs together and resolves sources and doses before protocol construction. +The models mirror config.toml. The CSV itself is read by ``lab.plugins.lmsf`` into a +``PlateDesign``; ``sources()`` resolves the configured stocks and cultures into the Lab +objects that ``lab.plates.assemble`` consumes. """ from dataclasses import dataclass @@ -9,20 +10,23 @@ from pydantic import Field, field_validator, model_validator -from lab import Quantity, uL +from lab import HamiltonLiquidClass, LiquidClass, Protocol, Well, uL from lab.config import ( Concentration, - ConcentrationUnit, ConfigModel, LiquidClassConfig, MixingConfig, NonemptyString, - NonnegativeDecimal, NonnegativeVolume, + PortableLiquidClassConfig, + PreparationConfig, Volume, VolumeFraction, ) from lab.deck import Deck +from lab.liquid_classes import LiquidClassSpec +from lab.plates import Mixing, Settings, Stock, Strategy +from lab.plugins.lmsf import material_name from lab.units import dilution_volume, magnitude WellName = Annotated[str, Field(strict=True, pattern=r"^[A-H](?:[1-9]|1[0-2])$")] @@ -39,8 +43,11 @@ class NamedSourceConfig(SourceConfig): class MediumConfig(NamedSourceConfig): - well: Literal["A1"] # The development deck binds reservoir A1. + """The base medium in reservoir A1; ``diluent_volume`` loads A2 for serial dilutions.""" + + well: Literal["A1"] dead_volume: NonnegativeVolume + diluent_volume: Volume | None = None class StockConfig(SourceConfig): @@ -73,6 +80,7 @@ class ProtocolConfig(ConfigModel): vehicle_fraction: VolumeFraction source_dead_volume: NonnegativeVolume solute_and_vehicle_free_medium_and_cultures: Annotated[bool, Field(strict=True)] + preparation: PreparationConfig = PreparationConfig() liquid_classes: dict[NonemptyString, LiquidClassConfig] medium: MediumConfig vehicle: NamedSourceConfig @@ -129,130 +137,103 @@ def compatible_inputs(self) -> Self: raise ValueError(f"{path}.liquid_class: unknown class {source.liquid_class!r}") return self - -class Condition(ConfigModel): - """One fitness CSV record; aliases preserve the source column names.""" - - position: Annotated[int, Field(ge=1, le=96)] - well: WellName - row: Annotated[str, Field(pattern=r"^[A-H]$")] - column: Annotated[int, Field(ge=1, le=12)] - strain: NonemptyString - plasmid: NonemptyString - inducer1_id: NonemptyString = Field(alias="inducer1Id") - inducer1_concentration: NonnegativeDecimal = Field(alias="inducer1Concentration") - inducer1_units: ConcentrationUnit = Field(alias="inducer1Units") - inducer2_id: NonemptyString = Field(alias="inducer2Id") - inducer2_concentration: NonnegativeDecimal = Field(alias="inducer2Concentration") - inducer2_units: ConcentrationUnit = Field(alias="inducer2Units") - selector_id: NonemptyString = Field(alias="selectorId") - selector_concentration: NonnegativeDecimal = Field(alias="selectorConc") - selector_units: ConcentrationUnit = Field(alias="selectorUnits") - - @field_validator("strain", "plasmid", "inducer1_id", "inducer2_id", "selector_id") - @classmethod - def assigned_name(cls, value: str) -> str: - if value == "none": - raise ValueError("Expected a known culture or solute assignment") - return value - - @model_validator(mode="after") - def consistent_record(self) -> Self: - if ( - self.well != f"{self.row}{self.column}" - or self.position != 8 * (self.column - 1) + ord(self.row) - 64 - ): - raise ValueError("Inconsistent position/row/column/well") - if len({self.inducer1_id, self.inducer2_id, self.selector_id}) != 3: - raise ValueError("Expected distinct solutes") - return self - - -class PlateLayout(ConfigModel): - """Validated fitness CSV records, retaining each physical well occurrence.""" - - conditions: Annotated[tuple[Condition, ...], Field(min_length=1)] - - @model_validator(mode="after") - def distinct_wells(self) -> Self: - if len({condition.well for condition in self.conditions}) != len(self.conditions): - raise ValueError("Repeated CSV destination") - return self - - -@dataclass(frozen=True) -class PreparedWell: - """A CSV condition with its source and doses resolved before recording operations.""" - - well: str - culture: CultureConfig - concentrations: dict[str, Quantity] - stock_volumes: tuple[tuple[StockConfig, Quantity], ...] - vehicle_volume: Quantity - medium_volume: Quantity + def settings(self, liquid_classes: dict[str, LiquidClassSpec]) -> Settings: + """Preparation settings for ``lab.plates.assemble`` from this configuration.""" + return Settings( + final_volume=self.final_volume, + inoculum_volume=self.inoculum_volume, + vehicle_fraction=self.vehicle_fraction, + strategy=Strategy(self.preparation.strategy), + concentrate=self.preparation.concentrate, + serial_min_steps=self.preparation.serial_min_steps, + premix_min_group=self.preparation.premix_min_group, + premix_overage=self.preparation.premix_overage, + source_mix=Mixing( + volume=self.source_mix.volume, + cycles=self.source_mix.cycles, + liquid_class=liquid_classes[self.source_mix.liquid_class], + ), + destination_mix=Mixing( + volume=self.destination_mix.volume, + cycles=self.destination_mix.cycles, + liquid_class=liquid_classes[self.destination_mix.liquid_class], + ), + ) -def prepare_wells(layout: PlateLayout, config: ProtocolConfig) -> list[PreparedWell]: - """Check the two inputs together and calculate each well's additions once.""" - conditions = {condition.well: condition for condition in layout.conditions} - selected_wells = config.wells if config.wells is not None else tuple(conditions) - if missing := set(selected_wells) - conditions.keys(): - raise ValueError(f"Selected wells absent from CSV: {sorted(missing)}") - cultures = {(culture.strain, culture.plasmid): culture for culture in config.cultures} - prepared_wells = [] - for well in selected_wells: - condition = conditions[well] - culture = cultures.get((condition.strain, condition.plasmid)) - if culture is None: - raise ValueError(f"{well}: no source for {condition.strain} / {condition.plasmid}") - # The CSV model has already parsed the numbers and checked the units. - targets = { - condition.inducer1_id: condition.inducer1_concentration * condition.inducer1_units, - condition.inducer2_id: condition.inducer2_concentration * condition.inducer2_units, - condition.selector_id: condition.selector_concentration * condition.selector_units, - } - doses: list[tuple[StockConfig, Quantity]] = [] - for solute, target in targets.items(): - if target.magnitude == 0: - continue - candidates = sorted( - (stock for stock in config.stocks if stock.solute == solute), - key=lambda stock: magnitude(stock.max_target, str(target.units), positive=False), - ) - selected = next((stock for stock in candidates if target <= stock.max_target), None) - if selected is None: - raise ValueError(f"{well}: no stock covers {solute} target {target}") - doses.append( - ( - selected, - dilution_volume( - stock_concentration=selected.concentration, - target_concentration=target, - final_volume=config.final_volume, - ), - ) - ) - vehicle_volume: Quantity = config.vehicle_fraction * config.final_volume - sum( - (stock.vehicle_fraction * dose for stock, dose in doses), 0 * uL +def liquid_classes(config: ProtocolConfig) -> dict[str, LiquidClassSpec]: + """Resolve named configuration entries into the Lab liquid classes used by the recipe.""" + return { + name: LiquidClass( + name, + aspiration_flow_rate=spec.aspiration_flow_rate, + dispense_flow_rate=spec.dispense_flow_rate, ) - medium_volume: Quantity = ( - config.final_volume - - config.inoculum_volume - - vehicle_volume - - sum((dose for _, dose in doses), 0 * uL) + if isinstance(spec, PortableLiquidClassConfig) + else HamiltonLiquidClass(spec.name) + for name, spec in config.liquid_classes.items() + } + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Sources: + """Declared and loaded sources, ready for ``lab.plates.assemble``.""" + + medium: Well + diluent: Well | None + vehicle: Well + waste: Well + stocks: tuple[Stock, ...] + inocula: dict[str, Well] + culture_wells: dict[str, CultureConfig] + + +def sources(p: Protocol, config: ProtocolConfig, classes: dict[str, LiquidClassSpec]) -> Sources: + """Declare the reservoirs and load every configured source into ``p``.""" + reagents = p.plate( + "reagents", shape=(1, 12), capacity=15000 * uL, dead_volume=config.source_dead_volume + ) + media = p.plate( + "medium", shape=(1, 2), capacity=15000 * uL, dead_volume=config.medium.dead_volume + ) + p.load(media["A1"], config.medium.name, volume=config.medium.volume) + diluent = None + if config.medium.diluent_volume is not None: + p.load(media["A2"], config.medium.name, volume=config.medium.diluent_volume) + diluent = media["A2"] + waste = p.container("waste", capacity=15000 * uL) + p.load(reagents[config.vehicle.well], config.vehicle.name, volume=config.vehicle.volume) + stocks = [] + for stock in config.stocks: + p.load( + reagents[stock.well], + f"{stock.solute}: {stock.concentration}; " + f"{config.vehicle.name} {stock.vehicle_fraction} v/v", + volume=stock.volume, ) - if vehicle_volume.magnitude < 0 or medium_volume.magnitude < 0: - raise ValueError( - f"{well}: stock/vehicle/inoculum additions exceed the final composition" - ) - prepared_wells.append( - PreparedWell( - well=well, - culture=culture, - concentrations=targets, - stock_volumes=tuple(doses), - vehicle_volume=vehicle_volume, - medium_volume=medium_volume, + stocks.append( + Stock( + solute=stock.solute, + concentration=stock.concentration, + source=reagents[stock.well], + max_target=stock.max_target, + vehicle_fraction=stock.vehicle_fraction, + liquid_class=classes[stock.liquid_class], ) ) - return prepared_wells + inocula: dict[str, Well] = {} + culture_wells: dict[str, CultureConfig] = {} + for culture in config.cultures: + material = material_name(culture.strain, culture.plasmid) + p.load(reagents[culture.well], material, volume=culture.volume) + inocula[material] = reagents[culture.well] + culture_wells[material] = culture + return Sources( + medium=media["A1"], + diluent=diluent, + vehicle=reagents[config.vehicle.well], + waste=waste, + stocks=tuple(stocks), + inocula=inocula, + culture_wells=culture_wells, + ) diff --git a/examples/concentration_series/protocol.py b/examples/concentration_series/protocol.py index e5a0bb4..9d215b6 100644 --- a/examples/concentration_series/protocol.py +++ b/examples/concentration_series/protocol.py @@ -1,165 +1,69 @@ -"""Record preparation operations from validated, prepared inputs.""" +"""Record preparation operations for a plate design using the configured sources.""" -from collections.abc import Sequence - -from examples.concentration_series.inputs import PreparedWell, ProtocolConfig -from lab import HamiltonLiquidClass, LiquidClass, Protocol, Quantity, Well, uL -from lab.config import PortableLiquidClassConfig -from lab.liquid_classes import LiquidClassSpec +from examples.concentration_series.inputs import ProtocolConfig, liquid_classes, sources +from lab import Protocol, uL +from lab.plates import AssemblyReport, PlateDesign, assemble from lab.samples import Sample -def protocol(prepared_wells: Sequence[PreparedWell], config: ProtocolConfig) -> Protocol: - """Add each reagent across the plate before inoculation and final mixing.""" - - # Resolve named configuration entries into the Lab settings used below. - liquid_classes: dict[str, LiquidClassSpec] = { - name: LiquidClass( - name, - aspiration_flow_rate=spec.aspiration_flow_rate, - dispense_flow_rate=spec.dispense_flow_rate, - ) - if isinstance(spec, PortableLiquidClassConfig) - else HamiltonLiquidClass(spec.name) - for name, spec in config.liquid_classes.items() - } +def protocol(design: PlateDesign, config: ProtocolConfig) -> tuple[Protocol, AssemblyReport]: + """Prepare every well of ``design`` before inoculation and final mixing.""" + classes = liquid_classes(config) p = Protocol( "CSV culture preparation", - description=f"Prepare {len(prepared_wells)} culture wells " + description=f"Prepare {len(design.wells)} culture wells " f"at {config.final_volume:~P} each. " "Concentrations refer to final volume after inoculation.\n\n" f"Protocol configuration: {config.model_dump_json(indent=2)}", ) - - # Hold prepared stocks, vehicle, and inocula in separate reservoir channels. - reagents = p.plate( - "reagents", shape=(1, 12), capacity=15000 * uL, dead_volume=config.source_dead_volume - ) + supplied = sources(p, config, classes) # Declare the culture plate; each selected well holds one experimental condition. - destinations = p.plate("cultures", capacity=360 * uL) - - # Record the available base medium used to bring cultures to their final volume. - medium = p.container( - "medium", - contents=config.medium.name, - volume=config.medium.volume, - capacity=15000 * uL, - dead_volume=config.medium.dead_volume, - ) + destinations = p.plate("cultures", shape=design.shape, capacity=360 * uL) - # Record the supplied vehicle used to balance the solvent fraction across conditions. - p.load(reagents[config.vehicle.well], config.vehicle.name, volume=config.vehicle.volume) - for stock in config.stocks: - - # Record each prepared solute stock, including its solvent contribution. - p.load( - reagents[stock.well], - f"{stock.solute}: {stock.concentration}; " - f"{config.vehicle.name} {stock.vehicle_fraction} v/v", - volume=stock.volume, - ) - for culture in config.cultures: - - # Record the supplied inoculum for this strain/plasmid pair. - p.load( - reagents[culture.well], f"{culture.strain} / {culture.plasmid}", volume=culture.volume - ) - - # Identify the parent culture so prepared wells retain their biological lineage. + # Identify each parent culture so prepared wells retain their biological lineage. + for material, well in supplied.inocula.items(): + culture = supplied.culture_wells[material] p.add_sample( Sample( id=f"inoculum-{culture.well}", material_identity=culture.plasmid, - label=f"{culture.strain} / {culture.plasmid}", + label=material, ), - at=reagents[culture.well], + at=well, is_input=True, ) - def add_across_plate( - source: Well, doses: Sequence[tuple[Well, Quantity]], liquid_class: LiquidClassSpec - ) -> None: - """Share a tip across equal doses; retain individual transfers for unique doses.""" - groups: dict[Quantity, list[Well]] = {} - for destination, dose in doses: - if dose.magnitude: - groups.setdefault(dose, []).append(destination) - for dose, wells in groups.items(): - if len(wells) == 1: - - # Supply a condition-specific dose from this source. - p.transfer(source, wells[0], volume=dose, liquid_class=liquid_class) - else: - - # Supply the same reagent dose to these conditions with one tip. - p.distribute(source, wells, volume=dose, liquid_class=liquid_class) - - # Establish the medium volume in every selected well before adding other reagents. - add_across_plate( - medium, - [(destinations[prepared.well], prepared.medium_volume) for prepared in prepared_wells], - liquid_classes[config.medium.liquid_class], - ) - - # Balance the solvent fraction across the selected conditions. - add_across_plate( - reagents[config.vehicle.well], - [(destinations[prepared.well], prepared.vehicle_volume) for prepared in prepared_wells], - liquid_classes[config.vehicle.liquid_class], + report = assemble( + p, + design, + plate=destinations, + stocks=supplied.stocks, + medium=supplied.medium, + diluent=supplied.diluent, + inocula=supplied.inocula, + settings=config.settings(classes), + vehicle=supplied.vehicle, + waste=supplied.waste, + medium_class=classes[config.medium.liquid_class], + vehicle_class=classes[config.vehicle.liquid_class], + culture_class=next((classes[c.liquid_class] for c in config.cultures), None), ) - for stock in config.stocks: - - # Add this working stock to every condition that uses it before changing sources. - add_across_plate( - reagents[stock.well], - [ - (destinations[prepared.well], dose) - for prepared in prepared_wells - for selected, dose in prepared.stock_volumes - if selected.well == stock.well - ], - liquid_classes[stock.liquid_class], - ) - - for prepared in prepared_wells: - well, culture = prepared.well, prepared.culture - destination = destinations[well] - - # Resuspend the source culture before withdrawing inoculum. - p.mix( - reagents[culture.well], - volume=config.source_mix.volume, - cycles=config.source_mix.cycles, - liquid_class=liquid_classes[config.source_mix.liquid_class], - ) - - # Inoculate this condition with the specified culture volume. - p.transfer( - reagents[culture.well], - destination, - volume=config.inoculum_volume, - liquid_class=liquid_classes[culture.liquid_class], - ) - - # Mix cells and reagents to homogenize the final culture. - p.mix( - destination, - volume=config.destination_mix.volume, - cycles=config.destination_mix.cycles, - liquid_class=liquid_classes[config.destination_mix.liquid_class], - ) - # Record this well's condition and link it to the source inoculum. + # Record each well's condition and link it to the source inoculum. + for plan in report.wells: + target = plan.target + assert target.material is not None + culture = supplied.culture_wells[target.material] p.add_sample( Sample( - id=f"culture-{well}", + id=f"culture-{target.well}", material_identity=culture.plasmid, - label=f"{well}: {culture.strain} / {culture.plasmid}; " - + ", ".join(f"{name} {value}" for name, value in prepared.concentrations.items()), + label=f"{target.well}: {target.material}; " + + ", ".join(f"{t.solute} {t.quantity:~P}" for t in target.targets), parent_ids=(f"inoculum-{culture.well}",), ), - at=destination, + at=destinations[target.well], is_output=True, ) - return p + return p, report diff --git a/src/lab/__init__.py b/src/lab/__init__.py index 37f5353..4006be5 100644 --- a/src/lab/__init__.py +++ b/src/lab/__init__.py @@ -4,7 +4,7 @@ from lab.compiler import Compilation, compile from lab.liquid_classes import HamiltonLiquidClass, LiquidClass from lab.protocol import Plate, Protocol, Well -from lab.units import Quantity, celsius, minutes, mL, seconds, uL +from lab.units import Quantity, celsius, minutes, mL, mM, seconds, uL, uM from lab.validation import CompileError __all__ = [ @@ -20,7 +20,9 @@ "celsius", "compile", "mL", + "mM", "minutes", "seconds", "uL", + "uM", ] diff --git a/src/lab/config.py b/src/lab/config.py index 4255a30..8f910e8 100644 --- a/src/lab/config.py +++ b/src/lab/config.py @@ -22,6 +22,7 @@ ) from lab.liquid_classes import HamiltonLiquidClass +from lab.plates.design import PlateDesign, well_target from lab.units import Quantity, parse_quantity, units # All quantities are finite. Concentrations can be molar or mass/volume; @@ -107,3 +108,44 @@ class MixingConfig(ConfigModel): volume: Volume cycles: Annotated[int, Field(strict=True, gt=0)] liquid_class: NonemptyString + + +WellName = Annotated[str, Field(strict=True, pattern=r"^[A-Z](?:[1-9]|[1-9][0-9])$")] + + +class WellTargetConfig(ConfigModel): + """One well of a plate design: an optional material and solute concentrations.""" + + well: WellName + material: NonemptyString | None = None + concentrations: dict[NonemptyString, Concentration] + + +class PlateDesignConfig(ConfigModel): + """A plate design as JSON or TOML; ``to_design()`` builds the Lab object.""" + + name: NonemptyString + shape: tuple[Annotated[int, Field(ge=1, le=26)], Annotated[int, Field(ge=1)]] = (8, 12) + final_volume: Volume + wells: Annotated[tuple[WellTargetConfig, ...], Field(min_length=1)] + + def to_design(self) -> PlateDesign: + return PlateDesign.build( + self.name, + shape=self.shape, + final_volume=self.final_volume, + wells=( + well_target(w.well, material=w.material, concentrations=w.concentrations) + for w in self.wells + ), + ) + + +class PreparationConfig(ConfigModel): + """How a design is turned into operations; mirrors ``lab.plates.recipe.Settings``.""" + + strategy: Literal["direct", "serial", "auto"] = "auto" + concentrate: Annotated[Decimal, Field(ge=1, allow_inf_nan=False)] = Decimal(2) + serial_min_steps: Annotated[int, Field(strict=True, ge=2)] = 4 + premix_min_group: Annotated[int, Field(strict=True, ge=2)] | None = None + premix_overage: Annotated[Decimal, Field(ge=1, allow_inf_nan=False)] = Decimal("1.1") diff --git a/src/lab/plates/__init__.py b/src/lab/plates/__init__.py new file mode 100644 index 0000000..7d85d5b --- /dev/null +++ b/src/lab/plates/__init__.py @@ -0,0 +1,63 @@ +"""Plate designs: the desired end state of a plate, the patterns in it, and its preparation.""" + +from lab.plates.arrange import ( + Arrangement, + ConditionSpec, + ControlSpec, + GradientSpec, + Requirements, + arrange, +) +from lab.plates.design import PlateDesign, Target, WellTarget, canonical_concentration, well_target +from lab.plates.dilution import SerialDilutionPlan, plan_serial_dilution, record_serial_dilution +from lab.plates.patterns import ( + ReplicateGroup, + SerialDilutionCandidate, + find_replicate_groups, + find_serial_dilutions, + parallelize, +) +from lab.plates.premix import PremixPlan, plan_premix, record_premix +from lab.plates.recipe import ( + AssemblyReport, + Mixing, + Settings, + Stock, + Strategy, + WellPlan, + assemble, + select_stock, +) + +__all__ = [ + "Arrangement", + "AssemblyReport", + "ConditionSpec", + "ControlSpec", + "GradientSpec", + "Mixing", + "PlateDesign", + "PremixPlan", + "ReplicateGroup", + "Requirements", + "SerialDilutionCandidate", + "SerialDilutionPlan", + "Settings", + "Stock", + "Strategy", + "Target", + "WellPlan", + "WellTarget", + "arrange", + "assemble", + "canonical_concentration", + "find_replicate_groups", + "find_serial_dilutions", + "parallelize", + "plan_premix", + "plan_serial_dilution", + "record_premix", + "record_serial_dilution", + "select_stock", + "well_target", +] diff --git a/src/lab/plates/arrange.py b/src/lab/plates/arrange.py new file mode 100644 index 0000000..523a464 --- /dev/null +++ b/src/lab/plates/arrange.py @@ -0,0 +1,190 @@ +"""Lay out a plate from abstract requirements instead of explicit well coordinates. + +Requirements are the product of materials, constant condition sets, and gradient levels, +plus individually specified controls. Gradients run along rows with the highest +concentration in the rightmost column, so one plate column holds one level and a +multichannel head moves column to column. Material and condition combinations stack down +the rows. +""" + +from collections.abc import Mapping +from dataclasses import dataclass +from decimal import Decimal +from itertools import product + +from lab.plates.design import PlateDesign, Target, WellTarget, canonical_concentration, well_name +from lab.units import Quantity, magnitude + + +def _targets(concentrations: Mapping[str, Quantity]) -> tuple[Target, ...]: + targets = [] + for solute, quantity in concentrations.items(): + value, unit = canonical_concentration(quantity) + targets.append(Target(solute=solute, magnitude=value, unit=unit)) + return tuple(targets) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class GradientSpec: + """A geometric series of one solute: ``steps`` levels from ``top`` down by ``fold``.""" + + solute: str + top: Quantity + fold: Decimal + steps: int + include_zero: bool = False + + def __post_init__(self) -> None: + if not isinstance(self.fold, Decimal) or not self.fold.is_finite() or self.fold < 2: + raise ValueError("Serial dilution folds below 2 do not fit a well; dose directly.") + if type(self.steps) is not int or self.steps < 2: + raise ValueError("A gradient needs at least two levels.") + canonical_concentration(self.top) + + def levels(self) -> tuple[Target, ...]: + """Targets from the top down, with an optional trailing zero control.""" + value, unit = canonical_concentration(self.top) + series = [value / self.fold**i for i in range(self.steps)] + if self.include_zero: + series.append(Decimal(0)) + return tuple(Target(solute=self.solute, magnitude=v, unit=unit) for v in series) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class ConditionSpec: + """Constant concentrations shared by a block of wells.""" + + label: str + concentrations: Mapping[str, Quantity] + + def targets(self) -> tuple[Target, ...]: + return _targets(self.concentrations) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class ControlSpec: + """Individually specified wells that take part in no gradient.""" + + label: str + concentrations: Mapping[str, Quantity] + replicates: int = 1 + + def targets(self) -> tuple[Target, ...]: + return _targets(self.concentrations) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Requirements: + name: str + final_volume: Quantity + materials: tuple[str, ...] + conditions: tuple[ConditionSpec, ...] + gradient: GradientSpec | None = None + controls: tuple[ControlSpec, ...] = () + replicates: int = 1 + shape: tuple[int, int] = (8, 12) + + def __post_init__(self) -> None: + if not self.materials or not self.conditions: + raise ValueError("Requirements need at least one material and one condition set.") + if type(self.replicates) is not int or self.replicates < 1: + raise ValueError("Replicates must be a positive integer.") + if self.gradient is not None: + for condition in self.conditions: + if self.gradient.solute in condition.concentrations: + raise ValueError( + f"{condition.label} fixes {self.gradient.solute}, the gradient solute." + ) + + @property + def series_length(self) -> int: + return len(self.gradient.levels()) if self.gradient else 1 + + @property + def well_count(self) -> int: + """The running count a design tool shows while requirements are edited.""" + series = len(self.materials) * len(self.conditions) * self.series_length + controls = sum(control.replicates for control in self.controls) * len(self.materials) + return series * self.replicates + controls + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Arrangement: + design: PlateDesign + unused_wells: tuple[str, ...] + rows: tuple[tuple[str, str, str], ...] + """(row, material, condition label) for each series row, in placement order.""" + + +def arrange(requirements: Requirements) -> Arrangement: + """Place series along rows and material x condition blocks down the plate. + + Raises ValueError with the overflow when the plate is too small, so a design tool can + report "over by N wells" rather than produce a partial layout. + """ + rows, columns = requirements.shape + capacity = rows * columns + if requirements.well_count > capacity: + raise ValueError( + f"{requirements.well_count} wells requested; a {rows}x{columns} plate holds " + f"{capacity} ({requirements.well_count - capacity} over)." + ) + if requirements.series_length > columns: + raise ValueError( + f"A {requirements.series_length}-level series does not fit {columns} columns." + ) + series_rows = len(requirements.materials) * len(requirements.conditions) + series_rows *= requirements.replicates + if series_rows > rows: + raise ValueError( + f"{series_rows} series rows requested; a {rows}x{columns} plate has {rows} rows." + ) + wells: list[WellTarget] = [] + row_log: list[tuple[str, str, str]] = [] + levels: tuple[Target | None, ...] = ( + requirements.gradient.levels() if requirements.gradient else (None,) + ) + # Series occupy the rightmost columns of their rows; controls fill from the left. + series_start = columns - len(levels) + limit = dict.fromkeys(range(rows), columns) + left = dict.fromkeys(range(rows), 0) + for row_index, (material, condition) in enumerate( + combination + for combination in product(requirements.materials, requirements.conditions) + for _ in range(requirements.replicates) + ): + row_log.append((chr(65 + row_index), material, condition.label)) + limit[row_index] = series_start + for offset, level in enumerate(reversed(levels)): + targets = condition.targets() + ((level,) if level is not None else ()) + wells.append( + WellTarget( + well=well_name(row_index, series_start + offset), + material=material, + targets=targets, + ) + ) + for material in requirements.materials: + for control in requirements.controls: + for _ in range(control.replicates): + open_rows = [r for r in range(rows) if left[r] < limit[r]] + if not open_rows: + raise ValueError("No free wells remain for controls; use a larger plate.") + row = min(open_rows, key=lambda r: (left[r], r)) + wells.append( + WellTarget( + well=well_name(row, left[row]), material=material, targets=control.targets() + ) + ) + left[row] += 1 + used = {w.well for w in wells} + unused = tuple( + well_name(r, c) for r in range(rows) for c in range(columns) if well_name(r, c) not in used + ) + design = PlateDesign( + name=requirements.name, + shape=requirements.shape, + final_volume_ul=magnitude(requirements.final_volume, "microliter"), + wells=tuple(wells), + ) + return Arrangement(design=design, unused_wells=unused, rows=tuple(row_log)) diff --git a/src/lab/plates/design.py b/src/lab/plates/design.py new file mode 100644 index 0000000..1ebc677 --- /dev/null +++ b/src/lab/plates/design.py @@ -0,0 +1,200 @@ +"""Target compositions for the wells of one plate, independent of how they are prepared.""" + +from collections.abc import Iterable, Mapping +from dataclasses import dataclass +from decimal import Decimal +from typing import Literal, Self + +from lab.units import Quantity, magnitude, units + +_DIMENSIONS = { + "[substance] / [length] ** 3": "mole/liter", + "[mass] / [length] ** 3": "gram/liter", +} + +Axis = Literal["row", "column"] + + +def canonical_concentration(value: Quantity) -> tuple[Decimal, str]: + """Normalize a concentration to a nonnegative Decimal in mole/liter or gram/liter.""" + if not isinstance(value, Quantity): + raise TypeError("A concentration must be a unit-bearing Quantity") + for dimensionality, unit in _DIMENSIONS.items(): + if value.check(dimensionality): + return magnitude(value, unit, positive=False), unit + raise ValueError("A concentration must have mass/volume or amount/volume units") + + +def well_name(row: int, column: int) -> str: + """Row-major well text for zero-based coordinates, matching ``Plate.wells``.""" + return f"{chr(65 + row)}{column + 1}" + + +def coordinates(well: str) -> tuple[int, int]: + """Zero-based (row, column) of a well name such as ``"H12"``.""" + if len(well) < 2 or not well[0].isalpha() or not well[1:].isdigit(): + raise ValueError(f"{well!r} is not a well name") + return ord(well[0].upper()) - 65, int(well[1:]) - 1 + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Target: + """One solute's intended final concentration in one well.""" + + solute: str + magnitude: Decimal + unit: str + + def __post_init__(self) -> None: + if not isinstance(self.solute, str) or not self.solute.strip(): + raise ValueError("A target needs a solute name.") + if self.unit not in _DIMENSIONS.values(): + raise ValueError("Target units must be mole/liter or gram/liter.") + if not isinstance(self.magnitude, Decimal) or not self.magnitude.is_finite(): + raise ValueError("A target concentration must be a finite Decimal.") + if self.magnitude < 0: + raise ValueError("A target concentration must be nonnegative.") + + @property + def quantity(self) -> Quantity: + return self.magnitude * units(self.unit) + + +Context = tuple[str | None, tuple[tuple[str, Decimal, str], ...]] + + +@dataclass(frozen=True, slots=True, kw_only=True) +class WellTarget: + """What one well must contain at the end: a material and solute concentrations.""" + + well: str + material: str | None + targets: tuple[Target, ...] + + def __post_init__(self) -> None: + coordinates(self.well) + if self.material is not None and not self.material.strip(): + raise ValueError(f"{self.well}: a material must be nonempty text or None.") + if not isinstance(self.targets, tuple): + raise TypeError("Targets must be a tuple of Target objects.") + solutes = [target.solute for target in self.targets] + if len(set(solutes)) != len(solutes): + raise ValueError(f"{self.well}: each solute may have one target.") + object.__setattr__(self, "targets", tuple(sorted(self.targets, key=lambda t: t.solute))) + + def concentration(self, solute: str) -> Target | None: + return next((target for target in self.targets if target.solute == solute), None) + + def context(self, *, excluding: str | None = None, ignore_material: bool = False) -> Context: + """A hashable key of everything except ``excluding``; equal keys mean the same diluent.""" + return ( + None if ignore_material else self.material, + tuple( + (target.solute, target.magnitude, target.unit) + for target in self.targets + if target.solute != excluding + ), + ) + + @property + def row(self) -> str: + return self.well[0] + + @property + def column(self) -> int: + return int(self.well[1:]) + + +def well_target( + well: str, *, material: str | None = None, concentrations: Mapping[str, Quantity] +) -> WellTarget: + """Build a WellTarget from unit-bearing quantities, for example ``{"Van": 100 * uM}``.""" + targets = [] + for solute, quantity in concentrations.items(): + value, unit = canonical_concentration(quantity) + targets.append(Target(solute=solute, magnitude=value, unit=unit)) + return WellTarget(well=well, material=material, targets=tuple(targets)) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class PlateDesign: + """The desired end state of a plate. It records no preparation steps.""" + + name: str + shape: tuple[int, int] = (8, 12) + final_volume_ul: Decimal + wells: tuple[WellTarget, ...] + + def __post_init__(self) -> None: + if not isinstance(self.name, str) or not self.name.strip(): + raise ValueError("A plate design needs a name.") + rows, columns = self.shape + if type(rows) is not int or type(columns) is not int or rows < 1 or columns < 1: + raise ValueError("Shape must contain two positive integers.") + if rows > 26: + raise ValueError("At most 26 named rows are supported.") + if not isinstance(self.wells, tuple): + raise TypeError("Wells must be a tuple of WellTarget objects.") + seen: set[str] = set() + for target in self.wells: + row, column = coordinates(target.well) + if not (0 <= row < rows and 0 <= column < columns): + raise ValueError(f"{target.well!r} is not a well of a {rows}x{columns} plate.") + if target.well in seen: + raise ValueError(f"{target.well} is specified twice.") + seen.add(target.well) + if ( + not isinstance(self.final_volume_ul, Decimal) + or not self.final_volume_ul.is_finite() + or self.final_volume_ul <= 0 + ): + raise ValueError("Final volume must be a positive finite Decimal.") + + @classmethod + def build( + cls, + name: str, + *, + final_volume: Quantity, + wells: Iterable[WellTarget], + shape: tuple[int, int] = (8, 12), + ) -> Self: + return cls( + name=name, + shape=shape, + final_volume_ul=magnitude(final_volume, "microliter"), + wells=tuple(wells), + ) + + def __getitem__(self, well: str) -> WellTarget: + for target in self.wells: + if target.well == well: + return target + raise KeyError(well) + + def __contains__(self, well: object) -> bool: + return any(target.well == well for target in self.wells) + + @property + def solutes(self) -> tuple[str, ...]: + return tuple(sorted({t.solute for w in self.wells for t in w.targets})) + + @property + def materials(self) -> tuple[str, ...]: + return tuple(sorted({w.material for w in self.wells if w.material is not None})) + + def row(self, row: str) -> tuple[WellTarget, ...]: + """Present wells in one row, in column order.""" + return tuple(sorted((w for w in self.wells if w.row == row), key=lambda w: w.column)) + + def column(self, column: int) -> tuple[WellTarget, ...]: + """Present wells in one column, in row order.""" + return tuple(sorted((w for w in self.wells if w.column == column), key=lambda w: w.row)) + + def lines(self, axis: Axis) -> tuple[tuple[WellTarget, ...], ...]: + rows, columns = self.shape + if axis == "row": + return tuple(self.row(chr(65 + r)) for r in range(rows)) + if axis == "column": + return tuple(self.column(c + 1) for c in range(columns)) + raise ValueError("axis must be 'row' or 'column'") diff --git a/src/lab/plates/dilution.py b/src/lab/plates/dilution.py new file mode 100644 index 0000000..8e679f7 --- /dev/null +++ b/src/lab/plates/dilution.py @@ -0,0 +1,128 @@ +"""Plan and record a serial dilution gradient from a detected candidate. + +Every well below the top is pre-filled with the gradient volume ``G`` of diluent. Moving ``t`` +from a well at concentration ``c`` into ``G`` gives ``c * t / (G + t)``; requiring ``c / f`` +gives ``t = G / (f - 1)``. Each well ends at ``G``, the top is prepared at ``G + t``, and the +bottom passes its surplus ``t`` to waste. Building at ``concentrate`` times the final +concentration in ``G = V / concentrate`` keeps the peak volume ``G + t`` inside the well; the +constant additions made afterwards bring every well to ``V`` and dilute the gradient solute by +exactly ``concentrate``. +""" + +from dataclasses import dataclass +from decimal import ROUND_CEILING, Decimal + +from lab.liquid_classes import LiquidClassSpec +from lab.plates.patterns import SerialDilutionCandidate +from lab.protocol import Plate, Protocol, Well +from lab.units import Quantity, magnitude, uL + + +@dataclass(frozen=True, slots=True, kw_only=True) +class SerialDilutionPlan: + """Volumes for one gradient, in microlitres.""" + + candidate: SerialDilutionCandidate + concentrate: Decimal + gradient_volume_ul: Decimal + transfer_volume_ul: Decimal + peak_volume_ul: Decimal + top_stock_ul: Decimal + top_diluent_ul: Decimal + + @property + def moves(self) -> int: + """Well-to-well transfers plus the final transfer to waste, per lane.""" + return self.candidate.steps * self.candidate.width + + +def plan_serial_dilution( + candidate: SerialDilutionCandidate, + *, + stock_concentration: Quantity, + final_volume: Quantity, + capacity: Quantity, + reserved: Quantity = 0 * uL, + concentrate: Decimal = Decimal(1), +) -> SerialDilutionPlan: + """Size a gradient built at ``concentrate`` times the final concentration. + + ``reserved`` is the volume every well still needs after the gradient (co-solutes, + vehicle, inoculum). Raises ValueError naming the minimum workable ``concentrate`` when + the peak mixing volume exceeds ``capacity``. + """ + if not isinstance(concentrate, Decimal) or not concentrate.is_finite() or concentrate < 1: + raise ValueError("concentrate must be a Decimal of at least 1.") + stock = magnitude(stock_concentration, candidate.unit) + volume = magnitude(final_volume, "microliter") + cap = magnitude(capacity, "microliter") + held = magnitude(reserved, "microliter", positive=False) + fold = candidate.fold + gradient = volume / concentrate + transfer = gradient / (fold - 1) + peak = gradient + transfer + if peak > cap: + minimum = (volume * fold / (cap * (fold - 1))).quantize(Decimal("0.01"), ROUND_CEILING) + raise ValueError( + f"Peak volume {peak} µL exceeds the {cap} µL well; " + f"use concentrate >= {minimum} or build the gradient in a deeper plate." + ) + if gradient + held > volume: + raise ValueError( + f"Gradient volume {gradient} µL plus {held} µL of later additions " + f"exceeds the {volume} µL final volume." + ) + top_concentration = candidate.top * concentrate + if top_concentration > stock: + raise ValueError( + f"{top_concentration} {candidate.unit} exceeds the stock at {stock} {candidate.unit}." + ) + top_stock = top_concentration / stock * peak + return SerialDilutionPlan( + candidate=candidate, + concentrate=concentrate, + gradient_volume_ul=gradient, + transfer_volume_ul=transfer, + peak_volume_ul=peak, + top_stock_ul=top_stock, + top_diluent_ul=peak - top_stock, + ) + + +def record_serial_dilution( + p: Protocol, + plan: SerialDilutionPlan, + *, + plate: Plate, + stock: Well, + diluent: Well, + waste: Well, + mix_cycles: int = 3, + stock_class: LiquidClassSpec | None = None, + diluent_class: LiquidClassSpec | None = None, +) -> None: + """Record diluent fills, the top dose, and the chain of mix-then-transfer moves. + + Levels are paired by index: level ``i`` well ``j`` feeds level ``i + 1`` well ``j``. The + bottom level passes its surplus to ``waste`` so every well ends at the gradient volume. + Zero-control wells receive the gradient volume of diluent and no stock. + """ + c = plan.candidate + top = [plate[w] for w in c.levels[0]] + below = [plate[w] for level in c.levels[1:] for w in level] + zeros = [plate[w] for w in c.zero_wells] + gradient = plan.gradient_volume_ul * uL + transfer = plan.transfer_volume_ul * uL + mix_volume = (plan.peak_volume_ul / 2) * uL + + p.distribute(diluent, top, volume=plan.top_diluent_ul * uL, liquid_class=diluent_class) + if below or zeros: + p.distribute(diluent, [*below, *zeros], volume=gradient, liquid_class=diluent_class) + p.distribute(stock, top, volume=plan.top_stock_ul * uL, liquid_class=stock_class) + for upper, lower in zip(c.levels, c.levels[1:], strict=False): + for source, destination in zip(upper, lower, strict=True): + p.mix(plate[source], volume=mix_volume, cycles=mix_cycles, liquid_class=stock_class) + p.transfer(plate[source], plate[destination], volume=transfer, liquid_class=stock_class) + for bottom in c.levels[-1]: + p.mix(plate[bottom], volume=mix_volume, cycles=mix_cycles, liquid_class=stock_class) + p.transfer(plate[bottom], waste, volume=transfer, liquid_class=stock_class) diff --git a/src/lab/plates/patterns.py b/src/lab/plates/patterns.py new file mode 100644 index 0000000..a334288 --- /dev/null +++ b/src/lab/plates/patterns.py @@ -0,0 +1,268 @@ +"""Recognize preparation patterns in a plate design: serial dilutions and replicates.""" + +from collections.abc import Sequence +from dataclasses import dataclass +from decimal import Decimal +from typing import Literal + +from lab.plates.design import Context, PlateDesign, WellTarget + +CandidateAxis = Literal["row", "column", "set"] + + +@dataclass(frozen=True, slots=True, kw_only=True) +class SerialDilutionCandidate: + """Wells whose concentrations of one solute form a geometric series in one diluent context. + + ``levels`` lists the top concentration first; every well in one level holds the same + concentration. A width above one means several lanes run in parallel, which is what a + multichannel head or several independent channels pipette in one stroke. + """ + + solute: str + unit: str + top: Decimal + fold: Decimal + levels: tuple[tuple[str, ...], ...] + axis: CandidateAxis + context: Context + zero_wells: tuple[str, ...] = () + + def __post_init__(self) -> None: + if len(self.levels) < 2 or any(not level for level in self.levels): + raise ValueError("A serial dilution needs at least two nonempty levels.") + if len({len(level) for level in self.levels}) != 1: + raise ValueError("Every level of a serial dilution holds the same number of wells.") + if self.fold <= 1 or self.top <= 0: + raise ValueError("A serial dilution needs a positive top and a fold above one.") + + @property + def steps(self) -> int: + return len(self.levels) + + @property + def width(self) -> int: + return len(self.levels[0]) + + @property + def wells(self) -> tuple[str, ...]: + return tuple(well for level in self.levels for well in level) + + def concentration(self, level: int) -> Decimal: + """The nominal concentration at ``level`` (zero is the top).""" + return self.top / self.fold**level + + +def _close(a: Decimal, b: Decimal, tolerance: Decimal) -> bool: + return abs(a - b) <= tolerance * max(abs(a), abs(b)) + + +def _snap(ratio: Decimal) -> Decimal: + """Present 2.0000000000000028 as 2 while keeping genuinely fractional folds.""" + rounded = ratio.quantize(Decimal("1e-9")).normalize() + integral = rounded.to_integral_value() + return integral if rounded == integral else rounded + + +def _runs( + values: Sequence[Decimal], *, min_fold: Decimal, min_steps: int, tolerance: Decimal +) -> list[tuple[int, int, Decimal]]: + """Maximal descending geometric runs as inclusive (start, end, fold) index triples.""" + runs: list[tuple[int, int, Decimal]] = [] + start = 0 + while start < len(values) - 1: + first, second = values[start], values[start + 1] + if first <= 0 or second <= 0 or first / second < min_fold * (1 - tolerance): + start += 1 + continue + fold = first / second + end = start + 1 + while end + 1 < len(values) and values[end + 1] > 0: + if not _close(values[end] / values[end + 1], fold, tolerance): + break + end += 1 + if end - start + 1 >= min_steps: + runs.append((start, end, _snap(fold))) + start = end + return runs + + +def _segments(line: Sequence[WellTarget], solute: str) -> list[list[WellTarget]]: + """Split a physical line into stretches that share material and every other solute.""" + segments: list[list[WellTarget]] = [] + for well in line: + if well.concentration(solute) is None: + segments.append([]) + continue + if ( + segments + and segments[-1] + and segments[-1][-1].context(excluding=solute) == well.context(excluding=solute) + ): + segments[-1].append(well) + else: + segments.append([well]) + return [segment for segment in segments if segment] + + +def _magnitude(well: WellTarget, solute: str) -> Decimal: + target = well.concentration(solute) + if target is None: + raise ValueError(f"{well.well} has no {solute} target") + return target.magnitude + + +def _unit(well: WellTarget, solute: str) -> str: + target = well.concentration(solute) + if target is None: + raise ValueError(f"{well.well} has no {solute} target") + return target.unit + + +def find_serial_dilutions( + design: PlateDesign, + solute: str, + *, + axis: CandidateAxis = "row", + min_fold: Decimal = Decimal(2), + min_steps: int = 3, + tolerance: Decimal = Decimal("1e-9"), +) -> tuple[SerialDilutionCandidate, ...]: + """Find geometric runs of ``solute`` whose other conditions are constant. + + ``axis="row"`` or ``"column"`` requires physical adjacency along that line, in either + direction. ``axis="set"`` ignores position: wells sharing a context are sorted by + concentration, so a scattered gradient is still reported, each level holding every well + at that concentration. A trailing well with the solute at zero in the same context is + attached as a zero control. + """ + if min_steps < 2: + raise ValueError("A serial dilution needs at least two levels.") + found: list[SerialDilutionCandidate] = [] + if axis == "set": + groups: dict[Context, list[WellTarget]] = {} + for well in design.wells: + if well.concentration(solute) is not None: + groups.setdefault(well.context(excluding=solute), []).append(well) + for context, members in groups.items(): + by_value: dict[Decimal, list[str]] = {} + for well in members: + by_value.setdefault(_magnitude(well, solute), []).append(well.well) + values = sorted(by_value, reverse=True) + unit = _unit(members[0], solute) + for start, end, fold in _runs( + values, min_fold=min_fold, min_steps=min_steps, tolerance=tolerance + ): + series = values[start : end + 1] + found.append( + SerialDilutionCandidate( + solute=solute, + unit=unit, + top=series[0], + fold=fold, + levels=tuple(tuple(sorted(by_value[v])) for v in series), + axis="set", + context=context, + zero_wells=tuple(sorted(by_value.get(Decimal(0), ()))), + ) + ) + return tuple(found) + if axis not in ("row", "column"): + raise ValueError("axis must be 'row', 'column', or 'set'") + for line in design.lines(axis): + for segment in _segments(line, solute): + for ordered in (segment, segment[::-1]): + values = [_magnitude(w, solute) for w in ordered] + for start, end, fold in _runs( + values, min_fold=min_fold, min_steps=min_steps, tolerance=tolerance + ): + chain = ordered[start : end + 1] + top = chain[0].concentration(solute) + assert top is not None + trailing = ordered[end + 1 : end + 2] + zeros = tuple(w.well for w in trailing if _magnitude(w, solute) == 0) + found.append( + SerialDilutionCandidate( + solute=solute, + unit=top.unit, + top=top.magnitude, + fold=fold, + levels=tuple((w.well,) for w in chain), + axis=axis, + context=chain[0].context(excluding=solute), + zero_wells=zeros, + ) + ) + return tuple(found) + + +def parallelize( + candidates: Sequence[SerialDilutionCandidate], *, tolerance: Decimal = Decimal("1e-9") +) -> tuple[SerialDilutionCandidate, ...]: + """Merge width-1 row candidates with equal solute, fold, top, and column path into one. + + Merged candidates have ``axis="column"``: each level is one plate column, listed in row + order, which an 8-channel head or several STAR channels move together. The context of the + first row is kept; the rows may assign different materials, since a gradient is built + before inoculation. + """ + groups: dict[tuple[str, Decimal, Decimal, tuple[int, ...]], list[SerialDilutionCandidate]] + groups = {} + for candidate in candidates: + if candidate.axis != "row" or candidate.width != 1: + raise ValueError("parallelize() merges single-width row candidates.") + columns = tuple(int(level[0][1:]) for level in candidate.levels) + key = next( + ( + k + for k in groups + if k[0] == candidate.solute + and k[2] == candidate.fold + and k[3] == columns + and _close(k[1], candidate.top, tolerance) + ), + (candidate.solute, candidate.top, candidate.fold, columns), + ) + groups.setdefault(key, []).append(candidate) + merged = [] + for members in groups.values(): + members.sort(key=lambda c: c.levels[0][0][0]) + first = members[0] + merged.append( + SerialDilutionCandidate( + solute=first.solute, + unit=first.unit, + top=first.top, + fold=first.fold, + axis="column", + levels=tuple(tuple(m.levels[i][0] for m in members) for i in range(first.steps)), + context=first.context, + zero_wells=tuple(z for m in members for z in m.zero_wells), + ) + ) + return tuple(merged) + + +@dataclass(frozen=True, slots=True, kw_only=True) +class ReplicateGroup: + """Wells with identical solute targets; ``materials`` lists what differs between them.""" + + context: Context + wells: tuple[str, ...] + materials: tuple[str | None, ...] + + +def find_replicate_groups(design: PlateDesign, *, min_size: int = 2) -> tuple[ReplicateGroup, ...]: + """Group wells by chemistry alone, so the shared portion can be prepared once.""" + groups: dict[Context, list[WellTarget]] = {} + for well in design.wells: + groups.setdefault(well.context(ignore_material=True), []).append(well) + return tuple( + ReplicateGroup( + context=context, + wells=tuple(w.well for w in members), + materials=tuple(w.material for w in members), + ) + for context, members in groups.items() + if len(members) >= min_size + ) diff --git a/src/lab/plates/premix.py b/src/lab/plates/premix.py new file mode 100644 index 0000000..68ed338 --- /dev/null +++ b/src/lab/plates/premix.py @@ -0,0 +1,86 @@ +"""Prepare the shared portion of replicate wells once, then distribute it. + +For ``n`` wells sharing a composition, the per-well portion is the sum of the doses identical +across the group. The tube holds ``n`` portions times an overage factor, so each component is +pipetted once at ``n`` times its per-well dose. +""" + +from collections.abc import Sequence +from dataclasses import dataclass +from decimal import Decimal + +from lab.liquid_classes import LiquidClassSpec +from lab.plates.patterns import ReplicateGroup +from lab.protocol import Plate, Protocol, Well +from lab.units import Quantity, magnitude, uL + + +@dataclass(frozen=True, slots=True, kw_only=True) +class PremixComponent: + source: Well + dose_ul: Decimal + liquid_class: LiquidClassSpec | None = None + + +@dataclass(frozen=True, slots=True, kw_only=True) +class PremixPlan: + group: ReplicateGroup + components: tuple[PremixComponent, ...] + overage: Decimal + portion_ul: Decimal + total_ul: Decimal + + def component_volume(self, component: PremixComponent) -> Decimal: + return component.dose_ul * len(self.group.wells) * self.overage + + +def plan_premix( + group: ReplicateGroup, + components: Sequence[tuple[Well, Quantity, LiquidClassSpec | None]], + *, + tube_capacity: Quantity, + overage: Decimal = Decimal("1.1"), +) -> PremixPlan: + """Size one tube for ``group``; raises ValueError when it would overflow the tube.""" + if not isinstance(overage, Decimal) or not overage.is_finite() or overage < 1: + raise ValueError("overage must be a Decimal of at least 1.") + parts = tuple( + PremixComponent(source=well, dose_ul=magnitude(dose, "microliter"), liquid_class=lc) + for well, dose, lc in components + ) + if not parts: + raise ValueError("A premix needs at least one component.") + portion = sum((part.dose_ul for part in parts), Decimal(0)) + total = portion * len(group.wells) * overage + cap = magnitude(tube_capacity, "microliter") + if total > cap: + raise ValueError(f"Premix of {total} µL exceeds the {cap} µL tube; split the group.") + return PremixPlan( + group=group, components=parts, overage=overage, portion_ul=portion, total_ul=total + ) + + +def record_premix( + p: Protocol, + plan: PremixPlan, + *, + tube: Well, + plate: Plate, + mix_cycles: int = 5, + mix_class: LiquidClassSpec | None = None, +) -> None: + """Assemble the tube largest component first, mix, then share one portion per well.""" + for part in sorted(plan.components, key=lambda c: c.dose_ul, reverse=True): + p.transfer( + part.source, + tube, + volume=plan.component_volume(part) * uL, + liquid_class=part.liquid_class, + ) + p.mix(tube, volume=(plan.total_ul / 2) * uL, cycles=mix_cycles, liquid_class=mix_class) + p.distribute( + tube, + [plate[w] for w in plan.group.wells], + volume=plan.portion_ul * uL, + liquid_class=mix_class, + ) diff --git a/src/lab/plates/recipe.py b/src/lab/plates/recipe.py new file mode 100644 index 0000000..0b1adfe --- /dev/null +++ b/src/lab/plates/recipe.py @@ -0,0 +1,371 @@ +"""Turn a plate design and a set of sources into recorded preparation operations. + +``assemble()`` records, in order: serial dilution gradients (diluent fills, top doses, and +chained transfers), premixes for replicate groups where enabled, medium to every remaining +well, vehicle balance, direct stock doses grouped by equal volume, inoculation, and a final +mix. Concentrations refer to the final volume after inoculation. +""" + +from collections.abc import Mapping, Sequence +from dataclasses import dataclass, replace +from decimal import Decimal +from enum import Enum + +from lab.liquid_classes import LiquidClassSpec +from lab.plates.design import Axis, PlateDesign, WellTarget, canonical_concentration +from lab.plates.dilution import SerialDilutionPlan, plan_serial_dilution, record_serial_dilution +from lab.plates.patterns import ( + SerialDilutionCandidate, + find_replicate_groups, + find_serial_dilutions, + parallelize, +) +from lab.plates.premix import PremixPlan, plan_premix, record_premix +from lab.protocol import Plate, Protocol, Well +from lab.units import Quantity, dilution_volume, magnitude, uL, units + + +class Strategy(Enum): + """How gradients in a design are prepared.""" + + DIRECT = "direct" + """Every dose comes straight from its stock.""" + SERIAL = "serial" + """Every detected gradient is a serial dilution; an infeasible gradient is an error.""" + AUTO = "auto" + """Serial where a gradient is detected and feasible, direct everywhere else.""" + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Stock: + """A prepared solution of one solute at a known concentration in a declared well.""" + + solute: str + concentration: Quantity + source: Well + max_target: Quantity | None = None + vehicle_fraction: Decimal = Decimal(0) + liquid_class: LiquidClassSpec | None = None + + def __post_init__(self) -> None: + value, _ = canonical_concentration(self.concentration) + if value <= 0: + raise ValueError(f"{self.solute}: a stock concentration must be positive.") + if self.max_target is not None: + canonical_concentration(self.max_target) + if not 0 <= self.vehicle_fraction <= 1: + raise ValueError(f"{self.solute}: vehicle fraction must be between 0 and 1.") + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Mixing: + volume: Quantity + cycles: int + liquid_class: LiquidClassSpec | None = None + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Settings: + """Preparation choices that are not part of the design itself.""" + + final_volume: Quantity + inoculum_volume: Quantity + vehicle_fraction: Decimal = Decimal(0) + strategy: Strategy = Strategy.AUTO + concentrate: Decimal = Decimal(2) + serial_min_steps: int = 4 + premix_min_group: int | None = None + premix_overage: Decimal = Decimal("1.1") + gradient_axis: Axis = "row" + source_mix: Mixing | None = None + destination_mix: Mixing | None = None + + +@dataclass(frozen=True, slots=True, kw_only=True) +class WellPlan: + """Resolved additions for one well; ``gradient_ul`` is what a serial dilution supplied.""" + + target: WellTarget + doses: tuple[tuple[Stock, Decimal], ...] + gradient_ul: Decimal + vehicle_ul: Decimal + medium_ul: Decimal + inoculum_ul: Decimal + premixed: bool = False + + +@dataclass(frozen=True, slots=True, kw_only=True) +class AssemblyReport: + wells: tuple[WellPlan, ...] + gradients: tuple[SerialDilutionPlan, ...] + premixes: tuple[PremixPlan, ...] + skipped_gradients: tuple[tuple[SerialDilutionCandidate, str], ...] = () + """Gradients ``Strategy.AUTO`` left to direct dosing, with the reason.""" + + +def _by_concentration(stock: Stock) -> Decimal: + return canonical_concentration(stock.concentration)[0] + + +def _covering(stock: Stock, target: Quantity) -> bool: + value, unit = canonical_concentration(target) + concentration = magnitude(stock.concentration, unit) + limit = magnitude(stock.max_target, unit, positive=False) if stock.max_target else None + return value <= concentration and (limit is None or value <= limit) + + +def select_stock(stocks: Sequence[Stock], solute: str, target: Quantity) -> Stock: + """The least concentrated stock whose declared limit covers ``target``.""" + eligible = [s for s in stocks if s.solute == solute and _covering(s, target)] + if not eligible: + raise ValueError(f"no stock covers {solute} target {target:~P}") + return min(eligible, key=_by_concentration) + + +def _gradient_stock( + stocks: Sequence[Stock], candidate: SerialDilutionCandidate, k: Decimal +) -> Stock: + top: Quantity = candidate.top * k * units(candidate.unit) + stock = select_stock(stocks, candidate.solute, top) + if stock.vehicle_fraction: + raise ValueError( + f"{candidate.solute}: a serial dilution of a vehicle-bearing stock needs a " + "vehicle-balanced diluent; dose it directly instead" + ) + return stock + + +def _plan_well( + target: WellTarget, + stocks: Sequence[Stock], + settings: Settings, + gradient: tuple[str, Decimal] | None, + vehicle: Well | None, +) -> WellPlan: + final = magnitude(settings.final_volume, "microliter") + inoculum = ( + magnitude(settings.inoculum_volume, "microliter", positive=False) + if target.material is not None + else Decimal(0) + ) + doses: list[tuple[Stock, Decimal]] = [] + for solute_target in target.targets: + if solute_target.magnitude == 0 or (gradient and solute_target.solute == gradient[0]): + continue + try: + stock = select_stock(stocks, solute_target.solute, solute_target.quantity) + except ValueError as exc: + raise ValueError(f"{target.well}: {exc}") from exc + dose = dilution_volume( + stock_concentration=stock.concentration, + target_concentration=solute_target.quantity, + final_volume=settings.final_volume, + ) + doses.append((stock, magnitude(dose, "microliter"))) + carried = sum((stock.vehicle_fraction * dose for stock, dose in doses), Decimal(0)) + vehicle_volume = settings.vehicle_fraction * final - carried + if vehicle is None and vehicle_volume != 0: + raise ValueError(f"{target.well}: balancing the vehicle fraction needs a vehicle source") + gradient_volume = gradient[1] if gradient else Decimal(0) + medium = ( + final + - inoculum + - gradient_volume + - vehicle_volume + - sum((dose for _, dose in doses), Decimal(0)) + ) + if vehicle_volume < 0 or medium < 0: + raise ValueError(f"{target.well}: additions exceed the final composition") + return WellPlan( + target=target, + doses=tuple(doses), + gradient_ul=gradient_volume, + vehicle_ul=vehicle_volume, + medium_ul=medium, + inoculum_ul=inoculum, + ) + + +def _add_grouped( + p: Protocol, + source: Well, + doses: Sequence[tuple[Well, Decimal]], + liquid_class: LiquidClassSpec | None, +) -> None: + """Share a tip across equal doses; retain individual transfers for unique doses.""" + groups: dict[Decimal, list[Well]] = {} + for destination, dose in doses: + if dose: + groups.setdefault(dose, []).append(destination) + for dose, wells in groups.items(): + if len(wells) == 1: + p.transfer(source, wells[0], volume=dose * uL, liquid_class=liquid_class) + else: + p.distribute(source, wells, volume=dose * uL, liquid_class=liquid_class) + + +def assemble( + p: Protocol, + design: PlateDesign, + *, + plate: Plate, + stocks: Sequence[Stock], + medium: Well, + inocula: Mapping[str, Well], + settings: Settings, + vehicle: Well | None = None, + waste: Well | None = None, + diluent: Well | None = None, + tubes: Sequence[Well] = (), + medium_class: LiquidClassSpec | None = None, + vehicle_class: LiquidClassSpec | None = None, + culture_class: LiquidClassSpec | None = None, +) -> AssemblyReport: + """Record the preparation of ``design`` into ``plate`` and report what was decided. + + ``inocula`` maps each design material to its source well. ``waste`` is required for + serial dilutions and ``tubes`` for premixes. Gradients draw their diluent from + ``diluent`` when given, otherwise from ``medium``; a separate well keeps one reservoir + from running dry, since every gradient lane discards one transfer volume to waste. + """ + if plate.shape != design.shape: + raise ValueError("The plate's shape must match the design") + final = magnitude(settings.final_volume, "microliter") + if design.final_volume_ul != final: + raise ValueError("Settings and design disagree on the final volume") + if missing := set(design.materials) - set(inocula): + raise ValueError(f"No inoculum source for {sorted(missing)}") + if type(settings.serial_min_steps) is not int or settings.serial_min_steps < 2: + raise ValueError("serial_min_steps must be an integer of at least 2") + + gradients: list[SerialDilutionPlan] = [] + skipped: list[tuple[SerialDilutionCandidate, str]] = [] + supplied: dict[str, tuple[str, Decimal]] = {} + if settings.strategy is not Strategy.DIRECT: + if waste is None: + raise ValueError("Serial dilutions need a waste container") + for solute in design.solutes: + candidates = find_serial_dilutions( + design, + solute, + axis=settings.gradient_axis, + min_steps=settings.serial_min_steps, + ) + if settings.gradient_axis == "row": + candidates = parallelize(candidates) + for candidate in candidates: + try: + stock = _gradient_stock(stocks, candidate, settings.concentrate) + plan = plan_serial_dilution( + candidate, + stock_concentration=stock.concentration, + final_volume=settings.final_volume, + capacity=p.capacity(plate), + reserved=settings.inoculum_volume, + concentrate=settings.concentrate, + ) + for well in (*candidate.wells, *candidate.zero_wells): + if well in supplied: + raise ValueError( + f"{well} takes part in two gradients; a two-dimensional " + "gradient needs an intermediate plate" + ) + except ValueError as exc: + if settings.strategy is Strategy.SERIAL: + raise + skipped.append((candidate, str(exc))) + continue + record_serial_dilution( + p, + plan, + plate=plate, + stock=stock.source, + diluent=diluent if diluent is not None else medium, + waste=waste, + stock_class=stock.liquid_class, + diluent_class=medium_class, + ) + gradients.append(plan) + for well in (*candidate.wells, *candidate.zero_wells): + supplied[well] = (solute, plan.gradient_volume_ul) + if settings.strategy is Strategy.SERIAL and not gradients: + raise ValueError("No serial dilution gradient was found in this design") + + plans = [ + _plan_well(target, stocks, settings, supplied.get(target.well), vehicle) + for target in design.wells + ] + + premixes: list[PremixPlan] = [] + if settings.premix_min_group is not None: + by_well = {plan.target.well: plan for plan in plans} + free_tubes = list(tubes) + for group in find_replicate_groups(design, min_size=settings.premix_min_group): + members = [by_well[w] for w in group.wells] + portions = { + (m.medium_ul, m.vehicle_ul, tuple((id(s), d) for s, d in m.doses)) for m in members + } + if len(portions) != 1: + continue + components: list[tuple[Well, Quantity, LiquidClassSpec | None]] = [] + first = members[0] + if first.medium_ul: + components.append((medium, first.medium_ul * uL, medium_class)) + if first.vehicle_ul and vehicle is not None: + components.append((vehicle, first.vehicle_ul * uL, vehicle_class)) + components.extend((s.source, d * uL, s.liquid_class) for s, d in first.doses) + if len(components) < 2: + continue + if not free_tubes: + raise ValueError("Premixing needs more tubes than were supplied") + tube = free_tubes.pop(0) + premix = plan_premix( + group, components, tube_capacity=p.capacity(tube), overage=settings.premix_overage + ) + record_premix(p, premix, tube=tube, plate=plate, mix_class=medium_class) + premixes.append(premix) + for index, well_plan in enumerate(plans): + if well_plan.target.well in group.wells: + plans[index] = replace(well_plan, premixed=True) + + direct = [well_plan for well_plan in plans if not well_plan.premixed] + _add_grouped(p, medium, [(plate[w.target.well], w.medium_ul) for w in direct], medium_class) + if vehicle is not None: + _add_grouped( + p, vehicle, [(plate[w.target.well], w.vehicle_ul) for w in direct], vehicle_class + ) + for stock in stocks: + _add_grouped( + p, + stock.source, + [(plate[w.target.well], d) for w in direct for s, d in w.doses if s is stock], + stock.liquid_class, + ) + for well_plan in plans: + if well_plan.target.material is None or not well_plan.inoculum_ul: + continue + source = inocula[well_plan.target.material] + destination = plate[well_plan.target.well] + if settings.source_mix is not None: + p.mix( + source, + volume=settings.source_mix.volume, + cycles=settings.source_mix.cycles, + liquid_class=settings.source_mix.liquid_class or culture_class, + ) + p.transfer( + source, destination, volume=well_plan.inoculum_ul * uL, liquid_class=culture_class + ) + if settings.destination_mix is not None: + p.mix( + destination, + volume=settings.destination_mix.volume, + cycles=settings.destination_mix.cycles, + liquid_class=settings.destination_mix.liquid_class or culture_class, + ) + return AssemblyReport( + wells=tuple(plans), + gradients=tuple(gradients), + premixes=tuple(premixes), + skipped_gradients=tuple(skipped), + ) diff --git a/src/lab/plugins/__init__.py b/src/lab/plugins/__init__.py new file mode 100644 index 0000000..e92e28b --- /dev/null +++ b/src/lab/plugins/__init__.py @@ -0,0 +1,5 @@ +"""Adapters between external file formats or systems and Lab's own types. + +Each plugin wraps core objects such as ``lab.plates.PlateDesign``; the core never depends on +a plugin. Plugins may require optional extras, which they import at module level. +""" diff --git a/src/lab/plugins/lmsf/__init__.py b/src/lab/plugins/lmsf/__init__.py new file mode 100644 index 0000000..bbbceb6 --- /dev/null +++ b/src/lab/plugins/lmsf/__init__.py @@ -0,0 +1,23 @@ +"""The LMSF destination-layout CSV as a view of a ``PlateDesign``. + +Requires ``lab-compiler[config]``. The schema assigns one strain/plasmid pair and three +solute targets to each well of a 96-well plate. +""" + +from lab.plugins.lmsf.layout import ( + LAYOUT_COLUMNS, + Condition, + material_name, + read_layout, + split_material, + write_layout, +) + +__all__ = [ + "LAYOUT_COLUMNS", + "Condition", + "material_name", + "read_layout", + "split_material", + "write_layout", +] diff --git a/src/lab/plugins/lmsf/layout.py b/src/lab/plugins/lmsf/layout.py new file mode 100644 index 0000000..63f195b --- /dev/null +++ b/src/lab/plugins/lmsf/layout.py @@ -0,0 +1,163 @@ +"""Read and write LMSF destination CSVs as plate designs.""" + +import csv +from decimal import Decimal +from io import StringIO +from typing import Annotated, Self + +from pydantic import Field, ValidationError, field_validator, model_validator + +from lab.config import ConcentrationUnit, ConfigModel, NonemptyString, NonnegativeDecimal +from lab.plates.design import PlateDesign, WellTarget, coordinates, well_target +from lab.units import Quantity, number, units + +LAYOUT_COLUMNS = ( + "position", + "well", + "row", + "column", + "inducer1Id", + "inducer1Concentration", + "inducer1Units", + "inducer2Id", + "inducer2Concentration", + "inducer2Units", + "selectorId", + "selectorConc", + "selectorUnits", + "strain", + "plasmid", +) +_SHOWN_UNITS = {"mole/liter": "umol/L", "gram/liter": "ug/mL"} +_WellName = Annotated[str, Field(strict=True, pattern=r"^[A-H](?:[1-9]|1[0-2])$")] + + +class Condition(ConfigModel): + """One LMSF fitness CSV record; aliases preserve the source column names.""" + + position: Annotated[int, Field(ge=1, le=96)] + well: _WellName + row: Annotated[str, Field(pattern=r"^[A-H]$")] + column: Annotated[int, Field(ge=1, le=12)] + strain: NonemptyString + plasmid: NonemptyString + inducer1_id: NonemptyString = Field(alias="inducer1Id") + inducer1_concentration: NonnegativeDecimal = Field(alias="inducer1Concentration") + inducer1_units: ConcentrationUnit = Field(alias="inducer1Units") + inducer2_id: NonemptyString = Field(alias="inducer2Id") + inducer2_concentration: NonnegativeDecimal = Field(alias="inducer2Concentration") + inducer2_units: ConcentrationUnit = Field(alias="inducer2Units") + selector_id: NonemptyString = Field(alias="selectorId") + selector_concentration: NonnegativeDecimal = Field(alias="selectorConc") + selector_units: ConcentrationUnit = Field(alias="selectorUnits") + + @field_validator("strain", "plasmid", "inducer1_id", "inducer2_id", "selector_id") + @classmethod + def assigned_name(cls, value: str) -> str: + if value == "none": + raise ValueError("Expected a known culture or solute assignment") + return value + + @model_validator(mode="after") + def consistent_record(self) -> Self: + if ( + self.well != f"{self.row}{self.column}" + or self.position != 8 * (self.column - 1) + ord(self.row) - 64 + ): + raise ValueError("Inconsistent position/row/column/well") + if len({self.inducer1_id, self.inducer2_id, self.selector_id}) != 3: + raise ValueError("Expected distinct solutes") + return self + + def to_well_target(self) -> WellTarget: + return well_target( + self.well, + material=material_name(self.strain, self.plasmid), + concentrations={ + self.inducer1_id: self.inducer1_concentration * self.inducer1_units, + self.inducer2_id: self.inducer2_concentration * self.inducer2_units, + self.selector_id: self.selector_concentration * self.selector_units, + }, + ) + + +def material_name(strain: str, plasmid: str) -> str: + """The design material text for one strain/plasmid pair.""" + return f"{strain} / {plasmid}" + + +def split_material(material: str | None) -> tuple[str, str]: + """Recover (strain, plasmid) from ``material_name`` text.""" + if material is None: + raise ValueError("LMSF rows need a strain and plasmid for every well") + strain, separator, plasmid = material.partition(" / ") + if not separator or not strain or not plasmid: + raise ValueError(f"{material!r} is not 'strain / plasmid' text") + return strain, plasmid + + +def read_layout(text: str, *, name: str, final_volume: Quantity) -> PlateDesign: + """Parse LMSF CSV text; every row is validated as a ``Condition`` first.""" + reader = csv.DictReader(StringIO(text.lstrip(""), newline="")) + if tuple(reader.fieldnames or ()) != LAYOUT_COLUMNS: + raise ValueError("Expected the LMSF fitness CSV schema; cytometry needs a separate recipe") + conditions = [] + for index, record in enumerate(reader): + try: + conditions.append(Condition.model_validate(record)) + except ValidationError as exc: + raise ValueError(f"CSV row {index + 2}: {exc}") from exc + if not conditions: + raise ValueError("The CSV has no destination rows") + return PlateDesign.build( + name, + final_volume=final_volume, + wells=(condition.to_well_target() for condition in conditions), + ) + + +def write_layout(design: PlateDesign, *, solute_order: tuple[str, str, str]) -> str: + """Emit LMSF rows in position order; ``solute_order`` names inducer1, inducer2, selector.""" + if len(set(solute_order)) != 3: + raise ValueError("solute_order names three distinct solutes") + if design.shape != (8, 12): + raise ValueError("LMSF layouts describe 96-well plates") + out = StringIO(newline="") + writer = csv.DictWriter(out, fieldnames=LAYOUT_COLUMNS, lineterminator="\n") + writer.writeheader() + for target in sorted(design.wells, key=lambda w: coordinates(w.well)[::-1]): + writer.writerow(_row(target, solute_order)) + return out.getvalue() + + +def _shown(target_magnitude: Decimal, unit: str) -> tuple[str, str]: + shown = _SHOWN_UNITS[unit] + converted: Decimal = Decimal(str((target_magnitude * units(unit)).to(shown).magnitude)) + return number(converted), shown + + +def _row(target: WellTarget, solute_order: tuple[str, str, str]) -> dict[str, str | int]: + if len(target.targets) != 3: + raise ValueError(f"{target.well}: LMSF rows carry exactly three solutes") + strain, plasmid = split_material(target.material) + row, column = coordinates(target.well) + values: dict[str, str | int] = { + "position": 8 * column + row + 1, + "well": target.well, + "row": target.row, + "column": target.column, + "strain": strain, + "plasmid": plasmid, + } + columns = ( + ("inducer1Id", "inducer1Concentration", "inducer1Units"), + ("inducer2Id", "inducer2Concentration", "inducer2Units"), + ("selectorId", "selectorConc", "selectorUnits"), + ) + for (id_key, value_key, unit_key), solute in zip(columns, solute_order, strict=True): + found = target.concentration(solute) + if found is None: + raise ValueError(f"{target.well}: no target for {solute}") + shown, unit = _shown(found.magnitude, found.unit) + values[id_key], values[value_key], values[unit_key] = solute, shown, unit + return values diff --git a/src/lab/protocol.py b/src/lab/protocol.py index a42fd11..8b97db5 100644 --- a/src/lab/protocol.py +++ b/src/lab/protocol.py @@ -24,7 +24,7 @@ Wait, ) from lab.samples import Location, Sample, SamplePlacement -from lab.units import magnitude, temperature +from lab.units import Quantity, magnitude, temperature, uL @dataclass(frozen=True) @@ -93,6 +93,18 @@ def __init__(self, name: str, *, description: str = "") -> None: def steps(self) -> tuple[Step, ...]: return tuple(self._steps) + def capacity(self, item: Plate | Well) -> Quantity: + """The declared working capacity of a plate's wells or of one well.""" + if isinstance(item, Well): + resource = self._resources.get(self._location(item).resource) + elif isinstance(item, Plate) and item._owner is self._owner: + resource = self._resources.get(item.name) + else: + raise ValueError("A plate or well must belong to this protocol") + if resource is None: + raise ValueError("Unknown plate") + return resource.capacity * uL + def plate( self, name: str, diff --git a/src/lab/units.py b/src/lab/units.py index 216741e..af81886 100644 --- a/src/lab/units.py +++ b/src/lab/units.py @@ -8,6 +8,8 @@ units = pint.UnitRegistry(non_int_type=Decimal) uL = units.microliter mL = units.milliliter +uM = units.micromolar +mM = units.millimolar seconds = units.second minutes = units.minute Quantity = pint.Quantity diff --git a/tests/test_concentration_series.py b/tests/test_concentration_series.py index 6fadd4d..f5fb94d 100644 --- a/tests/test_concentration_series.py +++ b/tests/test_concentration_series.py @@ -21,30 +21,40 @@ from lab.deck import Deck, HolderSite, Rail, Slot from lab.equipment import LiquidHandler from lab.model import Distribute, Mix, Transfer +from lab.plugins.lmsf import Condition, read_layout from lab.samples import Location -from lab.units import units ROOT = Path(__file__).resolve().parents[1] CSV = ROOT / "examples/concentration_series/layout.csv" CONFIG = ROOT / "examples/concentration_series/config.toml" -def configuration(): - return inputs.ProtocolConfig.model_validate(tomllib.loads(CONFIG.read_text())) +def configuration(strategy: str | None = None): + raw = tomllib.loads(CONFIG.read_text()) + if strategy is not None: + raw["preparation"]["strategy"] = strategy + return inputs.ProtocolConfig.model_validate(raw) def updated(config, **changes): return type(config).model_validate(config.model_dump() | changes) -def layout(path=CSV): - with path.open(newline="", encoding="utf-8-sig") as stream: - return inputs.PlateLayout.model_validate({"conditions": list(csv.DictReader(stream))}) +def design(path=CSV, config=None): + config = config or configuration() + return read_layout( + path.read_text(encoding="utf-8-sig"), name="cultures", final_volume=config.final_volume + ) + +def conditions(): + with CSV.open(newline="", encoding="utf-8-sig") as stream: + return [Condition.model_validate(row) for row in csv.DictReader(stream)] -def protocol(): - config = configuration() - return recipe.protocol(inputs.prepare_wells(layout(), config), config) + +def protocol(strategy: str | None = None): + config = configuration(strategy) + return recipe.protocol(design(config=config), config)[0] def delivered_transfers(steps): @@ -59,22 +69,26 @@ def delivered_transfers(steps): ] +def liquid_steps(steps): + return [step for step in steps if isinstance(step, (Transfer, Distribute, Mix))] + + try: from opentrons.simulate import simulate except ImportError: simulate = None -def test_preparation_matches_independent_doses_inventory_and_identity(): - bundle = compile(protocol(), to=None) +def test_direct_preparation_matches_independent_doses_inventory_and_identity(): + bundle = compile(protocol("direct"), to=None) transfers = delivered_transfers(bundle.protocol.steps) - conditions = layout().conditions + rows = conditions() expected = {f"{row}{column}" for row in "ABCDEFGH" for column in range(1, 13)} - assert {row.well for row in conditions} == expected + assert {row.well for row in rows} == expected assert configuration().wells is None samples = {sample.id: sample for sample in bundle.manifest.samples} - for row in conditions: + for row in rows: moves = [s for s in transfers if s.destination == Location("cultures", row.well)] # Independently balance all CSV targets against the supplied working stocks. @@ -118,6 +132,8 @@ def test_preparation_matches_independent_doses_inventory_and_identity(): ): assert abs(remaining[Location("reagents", well)] - Decimal(volume)) < Decimal("1e-12") assert abs(remaining[Location("medium", "A1")] - Decimal("547.75")) < Decimal("1e-12") + assert remaining[Location("medium", "A2")] == 10000 + assert remaining[Location("waste", "A1")] == 0 assert len(bundle.manifest.samples) == 96 assert {p.location.well for p in bundle.manifest.placements} == set(expected) assert '"name": "DMSO"' in bundle.protocol.description @@ -127,7 +143,7 @@ def test_preparation_matches_independent_doses_inventory_and_identity(): mixes = [s for s in bundle.protocol.steps if isinstance(s, Mix)] assert [(s.location, s.volume, s.cycles) for s in mixes] == [ item - for row in conditions + for row in rows for item in ( (Location("reagents", f"A{6 + (ord(row.row) - ord('A')) // 2}"), 50, 3), (Location("cultures", row.well), 100, 3), @@ -135,8 +151,8 @@ def test_preparation_matches_independent_doses_inventory_and_identity(): ] -def test_additions_are_grouped_by_source_and_dose_before_inoculation(): - steps = protocol().steps +def test_direct_additions_are_grouped_by_source_and_dose_before_inoculation(): + steps = protocol("direct").steps assert len(steps) == 327 assert all( isinstance(step, Distribute) and step.source.resource == "medium" for step in steps[:20] @@ -145,7 +161,7 @@ def test_additions_are_grouped_by_source_and_dose_before_inoculation(): assert len(distributions) == 39 assert len({(step.source, step.volume) for step in distributions}) == len(distributions) assert {destination.well for step in steps[:20] for destination in step.destinations} == { - row.well for row in layout().conditions + row.well for row in conditions() } first_inoculum_mix = next(index for index, step in enumerate(steps) if isinstance(step, Mix)) assert first_inoculum_mix == 39 @@ -155,12 +171,58 @@ def test_additions_are_grouped_by_source_and_dose_before_inoculation(): ) +def test_auto_strategy_builds_the_van_gradients_as_serial_dilutions(): + config = configuration() + assert config.preparation.strategy == "auto" + p, report = recipe.protocol(design(config=config), config) + bundle = compile(p, to=None) + assert [ + (g.candidate.solute, g.candidate.width, g.candidate.steps, g.candidate.fold) + for g in report.gradients + ] == [("Van", 4, 8, 2), ("Van", 4, 5, 2)] + assert report.skipped_gradients == () + plans = {plan.target.well: plan for plan in report.wells} + gradient_wells = { + w for g in report.gradients for w in (*g.candidate.wells, *g.candidate.zero_wells) + } + assert len(gradient_wells) == 4 * 8 + 4 * 5 + 4 + assert all(plans[w].gradient_ul == 100 for w in gradient_wells) + assert all(plans[w].gradient_ul == 0 for w in plans if w not in gradient_wells) + assert plans["A12"].medium_ul == 200 - 10 - 100 - 20 - 2 - 2 + + remaining = dict(bundle.final_volumes) + assert all(remaining[Location("cultures", w)] == 200 for w in plans) + assert remaining[Location("waste", "A1")] == 8 * 100 + # The gradient draws its diluent from the second medium well, not the dosing medium. + assert remaining[Location("medium", "A2")] < 10000 + van = [ + s + for s in delivered_transfers(bundle.protocol.steps) + if s.source in {Location("reagents", "A1"), Location("reagents", "A2")} + ] + tops = {w for g in report.gradients for w in g.candidate.levels[0]} + assert {s.destination.well for s in van if s.destination.well in gradient_wells} == tops + assert all(s.volume == 40 for s in van if s.destination.well in tops) + chain = [ + s + for s in bundle.protocol.steps + if isinstance(s, Transfer) and s.source.resource == "cultures" + ] + assert len(chain) == 8 * 4 + 5 * 4 + assert {s.volume for s in chain} == {Decimal(100)} + assert all(s.liquid_class is not None for s in bundle.protocol.steps) + assert len(bundle.protocol.steps) == 420 + assert "Serial dilutions" not in p.description # the CLI adds the gradient summary + assert len(bundle.manifest.samples) == 96 + + @pytest.mark.integration @pytest.mark.skipif(simulate is None, reason="Opentrons SDK not installed") -def test_generated_ot2_actions_match_transfers_mixes_and_tips(tmp_path, monkeypatch): +@pytest.mark.parametrize("strategy", ["direct", "auto"]) +def test_generated_ot2_actions_match_transfers_mixes_and_tips(tmp_path, monkeypatch, strategy): monkeypatch.chdir(tmp_path) bundle = compile( - protocol(), deck=configuration().deck, liquid_handler=LiquidHandler.OT2, to=None + protocol(strategy), deck=configuration().deck, liquid_handler=LiquidHandler.OT2, to=None ) log, _ = simulate(StringIO(bundle.files["protocol.py"])) texts = [event["payload"]["text"] for event in log] @@ -197,8 +259,8 @@ def test_generated_ot2_actions_match_transfers_mixes_and_tips(tmp_path, monkeypa assert actual.startswith(f"Mixing {expected_mix.cycles} times with a volume of ") volume = re.search(r"volume of ([0-9.]+)", actual) assert volume and Decimal(volume[1]) == expected_mix.volume - tips = len(bundle.protocol.steps) - assert tips == 327 + tips = len(liquid_steps(bundle.protocol.steps)) + assert tips == {"direct": 327, "auto": 420}[strategy] assert sum(t.startswith("Picking up tip") for t in texts) == tips assert sum(t.startswith("Dropping tip") for t in texts) == tips @@ -206,10 +268,10 @@ def test_generated_ot2_actions_match_transfers_mixes_and_tips(tmp_path, monkeypa @pytest.mark.parametrize( "change, message", [ - (lambda s: updated(s, cultures=()), "no source"), - (lambda s: updated(s, stocks=()), "no stock"), + (lambda s: updated(s, cultures=()), "No inoculum source"), + (lambda s: updated(s, stocks=()), "no stock covers"), (lambda s: updated(s, vehicle_fraction=Decimal("0.005")), "exceed"), - (lambda s: updated(s, final_volume=30 * uL), "available above its dead volume"), + (lambda s: updated(s, final_volume=30 * uL), "B7: additions exceed"), ( lambda s: updated( s, @@ -218,12 +280,16 @@ def test_generated_ot2_actions_match_transfers_mixes_and_tips(tmp_path, monkeypa "available above its dead volume", ), (lambda s: updated(s, vehicle=updated(s.vehicle, well="A1")), "assigned more than once"), + ( + lambda s: updated(s, medium=updated(s.medium, diluent_volume=None)), + "available above its dead volume", + ), ], ) def test_preparation_rejects_infeasible_or_unknown_inputs(change, message): with pytest.raises((ValueError, CompileError), match=message): config = change(configuration()) - compile(recipe.protocol(inputs.prepare_wells(layout(), config), config), to=None) + compile(recipe.protocol(design(config=config), config)[0], to=None) @pytest.mark.parametrize( @@ -240,6 +306,8 @@ def test_preparation_rejects_infeasible_or_unknown_inputs(change, message): ('liquid_class = "aqueous"', 'liquid_class = "missing"', "missing"), ('dispense_flow_rate = "30 uL/s"', 'dispense_flow_rate = "30 uL"', "compatible"), ('dispense_flow_rate = "30 uL/s"', 'dispense_fow_rate = "30 uL/s"', "Extra inputs"), + ('strategy = "auto"', 'strategy = "clever"', "direct"), + ('concentrate = "2"', 'concentrate = "0.5"', "greater than or equal to 1"), ], ) def test_preparation_file_validates_explicit_inputs(tmp_path, old, new, message): @@ -249,33 +317,6 @@ def test_preparation_file_validates_explicit_inputs(tmp_path, old, new, message) inputs.ProtocolConfig.model_validate(tomllib.loads(path.read_text())) -@pytest.mark.parametrize( - "key,value", - [ - ("well", "Z1"), - ("column", "2"), - ("position", "2"), - ("inducer1Concentration", "nan"), - ("inducer1Concentration", "-1"), - ("inducer1Units", "uL"), - ("inducer1Id", "Sal"), - ("plasmid", "none"), - ], -) -def test_csv_rejects_invalid_records_with_row_location(tmp_path, key, value): - with CSV.open(newline="") as stream: - rows = list(csv.DictReader(stream)) - rows[0][key] = value - path = tmp_path / "invalid.csv" - with path.open("w", newline="") as stream: - writer = csv.DictWriter(stream, fieldnames=rows[0].keys()) - writer.writeheader() - writer.writerows(rows) - with pytest.raises(ValidationError) as caught: - layout(path) - assert all(error["loc"][:2] == ("conditions", 0) for error in caught.value.errors()) - - def test_csv_targets_are_read_and_duplicate_conditions_remain_separate(tmp_path): with CSV.open(newline="") as stream: rows = list(csv.DictReader(stream)) @@ -288,7 +329,8 @@ def test_csv_targets_are_read_and_duplicate_conditions_remain_separate(tmp_path) writer.writeheader() writer.writerows(rows) config = updated(configuration(), wells=("A1", "A5")) - bundle = compile(recipe.protocol(inputs.prepare_wells(layout(path), config), config), to=None) + selected = cli.select(design(path, config), config.wells) + bundle = compile(recipe.protocol(selected, config)[0], to=None) van = [ s for s in delivered_transfers(bundle.protocol.steps) @@ -296,6 +338,8 @@ def test_csv_targets_are_read_and_duplicate_conditions_remain_separate(tmp_path) ] assert [(s.destination.well, s.volume) for s in van] == [("A1", 10), ("A5", 10)] assert len(bundle.manifest.samples) == 2 + with pytest.raises(ValueError, match="absent from CSV"): + cli.select(design(path, config), ("A1", "H12")) @pytest.mark.integration @@ -315,8 +359,9 @@ async def test_generated_star_example_tracks_all_delivered_volumes(): handler = await namespace["run"](backends.LiquidHandlerChatterboxBackend()) finally: plr.set_volume_tracking(False) + physical = {binding.location: binding.physical for binding in bundle.target.bindings} for location, volume in bundle.final_volumes: - resource = handler.deck.get_resource(location.resource).get_item(location.well) + resource = handler.deck.get_resource(physical[location]) # The SDK accumulates binary floats, while the compiler retains decimal doses. assert abs(Decimal(str(resource.tracker.get_used_volume())) - volume) < Decimal("1e-8") @@ -324,14 +369,17 @@ async def test_generated_star_example_tracks_all_delivered_volumes(): def test_explicit_subset_preserves_requested_order_and_culture_assignments(): config = updated(configuration(), wells=("H12", "A1")) - prepared = inputs.prepare_wells(layout(), config) - assert [well.well for well in prepared] == ["H12", "A1"] - assert [well.culture.plasmid for well in prepared] == [ - "example-plasmid-4", - "example-plasmid-1", + selected = cli.select(design(config=config), config.wells) + assert [well.well for well in selected.wells] == ["H12", "A1"] + p, report = recipe.protocol(selected, config) + assert [plan.target.material for plan in report.wells] == [ + "example-strain / example-plasmid-4", + "example-strain / example-plasmid-1", ] - bundle = compile(recipe.protocol(prepared, config), to=None) + bundle = compile(p, to=None) assert {placement.location.well for placement in bundle.manifest.placements} == {"H12", "A1"} + # Two isolated wells contain no gradient, so the automatic strategy doses directly. + assert report.gradients == () def test_config_round_trip_preserves_toml_shape_and_resolves_classes_explicitly(): @@ -349,9 +397,11 @@ def test_config_round_trip_preserves_toml_shape_and_resolves_classes_explicitly( ) assert config.medium.name == raw["medium"]["name"] assert config.medium.dead_volume == 500 * uL + assert config.medium.diluent_volume == 10000 * uL assert config.medium.liquid_class == "aqueous" assert config.source_mix.liquid_class == "culture" assert config.stocks[0].well == raw["stocks"][0]["well"] + assert config.preparation.concentrate == 2 assert isinstance(config.deck, Deck) ot2 = config.deck.layout_for(LiquidHandler.OT2) star = config.deck.layout_for(LiquidHandler.STAR) @@ -368,14 +418,14 @@ def test_config_round_trip_preserves_toml_shape_and_resolves_classes_explicitly( } native_config = inputs.ProtocolConfig.model_validate(raw) assert native_config.medium.liquid_class == "aqueous" - bundle = compile( - recipe.protocol(inputs.prepare_wells(layout(), native_config), native_config), to=None - ) + bundle = compile(recipe.protocol(design(config=native_config), native_config)[0], to=None) medium_class = bundle.protocol.steps[0].liquid_class assert isinstance(medium_class, HamiltonLiquidClass) assert medium_class.name == "HighVolumeFilter_Water_DispenseSurface_Part" mixing_class = next( - step for step in bundle.protocol.steps if isinstance(step, Mix) + step + for step in bundle.protocol.steps + if isinstance(step, Mix) and step.location.resource == "reagents" ).liquid_class assert isinstance(mixing_class, LiquidClass) assert mixing_class.name == "culture" @@ -411,6 +461,12 @@ def test_config_round_trip_preserves_toml_shape_and_resolves_classes_explicitly( "value_error", ), (("cultures", 0, "well"), "A13", ("cultures", 0, "well"), "string_pattern_mismatch"), + ( + ("preparation", "serial_min_steps"), + 1, + ("preparation", "serial_min_steps"), + "greater_than_equal", + ), ], ) def test_config_validation_reports_the_invalid_field(path, value, location, error_type): @@ -430,14 +486,13 @@ def test_saved_config_is_the_validated_input_used_by_the_recipe(): final_volume="180 uL", medium=updated(configuration().medium, name="Specified medium"), ) - bundle = compile(recipe.protocol(inputs.prepare_wells(layout(), config), config), to=None) + bundle = compile(recipe.protocol(design(config=config), config)[0], to=None) recorded = json.loads(bundle.protocol.description.split("Protocol configuration: ", 1)[1]) assert recorded == config.model_dump(mode="json") assert recorded["final_volume"] == "180 microliter" assert recorded["medium"]["name"] == "Specified medium" assert all( - dict(bundle.final_volumes)[Location("cultures", row.well)] == 180 - for row in layout().conditions + dict(bundle.final_volumes)[Location("cultures", row.well)] == 180 for row in conditions() ) with pytest.raises(ValidationError, match="less than final"): updated(config, inoculum_volume=200 * uL) @@ -449,45 +504,29 @@ def test_config_schema_describes_nested_inputs_and_unit_strings(): assert schema["properties"]["final_volume"]["type"] == "string" assert schema["$defs"]["MediumConfig"]["properties"]["dead_volume"]["type"] == "string" assert schema["$defs"]["MediumConfig"]["properties"]["liquid_class"]["type"] == "string" + assert schema["$defs"]["PreparationConfig"]["properties"]["strategy"]["enum"] == [ + "direct", + "serial", + "auto", + ] -def test_csv_model_parses_typed_records_and_round_trips_source_columns(): - parsed = layout() - row = next(condition for condition in parsed.conditions if condition.well == "A5") - assert row.position == 33 - assert row.inducer1_concentration == Decimal("0.78125") - assert row.inducer1_concentration * row.inducer1_units == units("0.78125 umol/liter") - saved = parsed.model_dump_json(by_alias=True) - assert "inducer1Concentration" in json.loads(saved)["conditions"][0] - assert inputs.PlateLayout.model_validate_json(saved) == parsed - - -@pytest.mark.parametrize("count, message", [(0, "at least 1"), (2, "Repeated CSV destination")]) -def test_csv_model_rejects_empty_layouts_and_repeated_destinations(count, message): - row = layout().conditions[0] - with pytest.raises(ValidationError, match=message): - inputs.PlateLayout.model_validate({"conditions": [row] * count}) - - -def test_protocol_consumes_prepared_inputs_without_parsing_or_recalculating(monkeypatch): +def test_protocol_consumes_the_design_without_reading_files(monkeypatch): config = configuration() - prepared = inputs.prepare_wells(layout(), config) + plate = design(config=config) def unexpected(*args, **kwargs): - pytest.fail("Protocol construction must consume the already prepared inputs") + pytest.fail("Protocol construction must consume the already parsed inputs") with monkeypatch.context() as patch: patch.setattr(inputs.ProtocolConfig, "model_validate", unexpected) - patch.setattr(inputs.PlateLayout, "model_validate", unexpected) - patch.setattr(inputs, "prepare_wells", unexpected) - patch.setattr(inputs, "dilution_volume", unexpected) patch.setattr(Path, "open", unexpected) patch.setattr(Path, "read_bytes", unexpected) - p = recipe.protocol(prepared, config) + patch.setattr(Path, "read_text", unexpected) + p, _ = recipe.protocol(plate, config) bundle = compile(p, to=None) assert all( - dict(bundle.final_volumes)[Location("cultures", row.well)] == 200 - for row in layout().conditions + dict(bundle.final_volumes)[Location("cultures", row.well)] == 200 for row in conditions() ) @@ -508,23 +547,45 @@ def test_cli_replaces_existing_bundle_with_current_inputs(tmp_path, monkeypatch, description = plan["protocol"]["description"] assert CSV.name in description assert hashlib.sha256(CSV.read_bytes()).hexdigest() in description + assert "Serial dilutions: Van 8-step 2-fold across 4 rows" in description assert json.loads( description.split("Protocol configuration: ", 1)[1] ) == configuration().model_dump(mode="json") - assert len(plan["protocol"]["steps"]) == 327 + assert len(plan["protocol"]["steps"]) == 420 assert "Previous compilation" not in (output / "protocol.html").read_text() assert len(json.loads((output / "manifest.json").read_text())["outputs"]) == 96 assert not (output / "protocol.py").exists() assert (output / "notes.txt").read_text() == "Keep these notes" +def test_cli_strategy_flag_overrides_the_configured_strategy(tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + monkeypatch.setattr( + sys, + "argv", + [ + "concentration_series", + "--csv", + str(CSV), + "--config", + str(CONFIG), + "--strategy", + "direct", + ], + ) + cli.main() + plan = json.loads((tmp_path / "build/concentration_series/csv/manual/plan.json").read_text()) + assert len(plan["protocol"]["steps"]) == 327 + assert "Serial dilutions" not in plan["protocol"]["description"] + + @pytest.mark.parametrize( "config_change, csv_change, message", [ (None, ("0.78125", "NaN"), "finite"), (None, ("inducer1Units", "unknownColumn"), "CSV schema"), (None, ("A5,A,5", "A5,A,6"), "Inconsistent position"), - (None, ("example-plasmid-1", "unknown-plasmid"), "no source"), + (None, ("example-plasmid-1", "unknown-plasmid"), "No inoculum source"), ( ('final_volume = "200 uL"', 'wells = ["A1", "A13"]\nfinal_volume = "200 uL"'), None, @@ -553,7 +614,8 @@ def test_cli_rejects_invalid_inputs_before_protocol_construction( def unexpected(*args, **kwargs): pytest.fail("Invalid inputs must be rejected before protocol construction") - monkeypatch.setattr(cli, "protocol", unexpected) + if message not in {"No inoculum source", "no stock", "exceed"}: + monkeypatch.setattr(cli, "protocol", unexpected) with pytest.raises(SystemExit) as caught: cli.main() assert caught.value.code == 2 diff --git a/tests/test_lmsf_plugin.py b/tests/test_lmsf_plugin.py new file mode 100644 index 0000000..18f5748 --- /dev/null +++ b/tests/test_lmsf_plugin.py @@ -0,0 +1,103 @@ +"""The LMSF destination CSV as a view of a plate design.""" + +import csv +import json +from decimal import Decimal +from io import StringIO +from pathlib import Path + +import pytest +from pydantic import ValidationError + +from lab import uL +from lab.plates import PlateDesign, find_serial_dilutions, parallelize, well_target +from lab.plugins.lmsf import Condition, material_name, read_layout, split_material, write_layout +from lab.units import units + +CSV = Path(__file__).resolve().parents[1] / "examples/concentration_series/layout.csv" + + +def test_layout_round_trips_byte_for_byte_and_describes_the_plate(): + text = CSV.read_text() + design = read_layout(text, name="cultures", final_volume=200 * uL) + assert len(design.wells) == 96 and design.solutes == ("Sal", "TMP", "Van") + assert design.materials == tuple(f"example-strain / example-plasmid-{i}" for i in range(1, 5)) + a5 = design["A5"] + assert a5.concentration("Van").quantity == units("0.78125 umol/liter") + assert a5.concentration("TMP").unit == "gram/liter" + assert write_layout(design, solute_order=("Van", "Sal", "TMP")) == text + van = parallelize(find_serial_dilutions(design, "Van")) + assert [(c.levels[0], c.steps, c.zero_wells) for c in van] == [ + (("A12", "C12", "E12", "G12"), 8, ()), + (("B12", "D12", "F12", "H12"), 5, ("B7", "D7", "F7", "H7")), + ] + sal = find_serial_dilutions(design, "Sal") + assert [(c.levels[0][0], c.steps, c.fold) for c in sal][:2] == [("A1", 3, 2), ("B1", 3, 2)] + assert sal[1].top == Decimal("0.0000142857142857143") + + +def test_condition_model_parses_typed_records_and_round_trips_source_columns(): + with CSV.open(newline="") as stream: + rows = list(csv.DictReader(stream)) + row = Condition.model_validate(next(r for r in rows if r["well"] == "A5")) + assert row.position == 33 and row.inducer1_concentration == Decimal("0.78125") + saved = json.loads(row.model_dump_json(by_alias=True)) + assert saved["inducer1Concentration"] == "0.78125" + assert row.inducer1_concentration * row.inducer1_units == units("0.78125 umol/liter") + assert Condition.model_validate_json(row.model_dump_json(by_alias=True)) == row + assert split_material(material_name("s", "p")) == ("s", "p") + with pytest.raises(ValueError, match="strain / plasmid"): + split_material("no separator") + + +@pytest.mark.parametrize( + "key,value", + [ + ("well", "Z1"), + ("column", "2"), + ("position", "2"), + ("inducer1Concentration", "nan"), + ("inducer1Concentration", "-1"), + ("inducer1Units", "uL"), + ("inducer1Id", "Sal"), + ("plasmid", "none"), + ], +) +def test_layout_rejects_invalid_records_with_row_location(key, value): + with CSV.open(newline="") as stream: + rows = list(csv.DictReader(stream)) + rows[0][key] = value + with pytest.raises(ValidationError): + Condition.model_validate(rows[0]) + text = _text(rows) + with pytest.raises(ValueError, match="CSV row 2"): + read_layout(text, name="cultures", final_volume=200 * uL) + + +def _text(rows): + out = StringIO() + writer = csv.DictWriter(out, fieldnames=rows[0].keys(), lineterminator="\n") + writer.writeheader() + writer.writerows(rows) + return out.getvalue() + + +def test_layout_rejects_wrong_schema_empty_files_and_repeated_wells(): + text = CSV.read_text() + with pytest.raises(ValueError, match="CSV schema"): + read_layout(text.replace("inducer1Units", "unknownColumn"), name="c", final_volume=1 * uL) + with pytest.raises(ValueError, match="no destination rows"): + read_layout(text.splitlines()[0] + "\n", name="c", final_volume=1 * uL) + lines = text.splitlines(True) + with pytest.raises(ValueError, match="specified twice"): + read_layout("".join(lines[:2] + lines[1:2]), name="c", final_volume=1 * uL) + + +def test_write_layout_requires_three_solutes_and_a_material(): + design = PlateDesign.build( + "p", final_volume=1 * uL, wells=[well_target("A1", concentrations={"Van": 1 * units("uM")})] + ) + with pytest.raises(ValueError, match="exactly three solutes"): + write_layout(design, solute_order=("Van", "Sal", "TMP")) + with pytest.raises(ValueError, match="three distinct"): + write_layout(design, solute_order=("Van", "Van", "TMP")) diff --git a/tests/test_plates.py b/tests/test_plates.py new file mode 100644 index 0000000..f78d63c --- /dev/null +++ b/tests/test_plates.py @@ -0,0 +1,478 @@ +"""Plate designs, pattern detection, serial dilution arithmetic, premixes, and arrangement.""" + +from decimal import Decimal + +import pytest + +from lab import Protocol, compile, uL, uM +from lab.model import Distribute, Mix, Transfer +from lab.plates import ( + ConditionSpec, + ControlSpec, + GradientSpec, + PlateDesign, + Requirements, + Settings, + Stock, + Strategy, + Target, + WellTarget, + arrange, + assemble, + find_replicate_groups, + find_serial_dilutions, + parallelize, + plan_premix, + plan_serial_dilution, + record_premix, + record_serial_dilution, + well_target, +) +from lab.plates.design import canonical_concentration +from lab.samples import Location +from lab.units import units + +UG_ML = units("ug/mL") + + +def gradient_design(*, zero: bool = False, sal: tuple[Decimal, Decimal] = (Decimal(10),) * 2): + """Two row pairs with a 2-fold Van series from column 12 down to column 5.""" + wells = [] + for row, plasmid, level in (("A", "p1", 0), ("B", "p1", 1), ("C", "p2", 0), ("D", "p2", 1)): + for column in range(5, 13): + van = Decimal(100) / Decimal(2) ** (12 - column) + wells.append( + well_target( + f"{row}{column}", + material=f"strain / {plasmid}", + concentrations={"Van": van * uM, "Sal": sal[level] * uM, "TMP": 3 * UG_ML}, + ) + ) + if zero: + wells.append( + well_target( + f"{row}4", + material=f"strain / {plasmid}", + concentrations={"Van": 0 * uM, "Sal": sal[level] * uM, "TMP": 3 * UG_ML}, + ) + ) + return PlateDesign.build("cultures", final_volume=200 * uL, wells=wells) + + +def test_design_normalizes_units_sorts_targets_and_rejects_duplicates(): + assert canonical_concentration(100 * uM) == (Decimal("0.0001"), "mole/liter") + assert canonical_concentration(3 * UG_ML) == (Decimal("0.003"), "gram/liter") + with pytest.raises(ValueError, match="mass/volume or amount/volume"): + canonical_concentration(3 * uL) + target = well_target("A1", concentrations={"Van": 1 * uM, "Sal": 2 * uM}) + assert [t.solute for t in target.targets] == ["Sal", "Van"] + assert target.context(excluding="Van") == (None, (("Sal", Decimal("0.000002"), "mole/liter"),)) + with pytest.raises(ValueError, match="one target"): + WellTarget( + well="A1", + material=None, + targets=( + Target(solute="Van", magnitude=Decimal(1), unit="mole/liter"), + Target(solute="Van", magnitude=Decimal(2), unit="mole/liter"), + ), + ) + with pytest.raises(ValueError, match="specified twice"): + PlateDesign.build("p", final_volume=1 * uL, wells=[target, target]) + with pytest.raises(ValueError, match="not a well of a 8x12"): + PlateDesign.build("p", final_volume=1 * uL, wells=[well_target("I1", concentrations={})]) + design = gradient_design() + assert design.solutes == ("Sal", "TMP", "Van") + assert design.materials == ("strain / p1", "strain / p2") + assert [w.well for w in design.row("A")] == [f"A{c}" for c in range(5, 13)] + assert [w.well for w in design.column(12)] == ["A12", "B12", "C12", "D12"] + assert "A12" in design and "H1" not in design + + +def test_detects_gradients_along_rows_and_merges_them_into_columns(): + design = gradient_design(zero=True, sal=(Decimal(10), Decimal(25))) + found = find_serial_dilutions(design, "Van") + assert [(c.levels[0][0], c.levels[-1][0], c.steps, c.fold, c.zero_wells) for c in found] == [ + ("A12", "A5", 8, Decimal(2), ("A4",)), + ("B12", "B5", 8, Decimal(2), ("B4",)), + ("C12", "C5", 8, Decimal(2), ("C4",)), + ("D12", "D5", 8, Decimal(2), ("D4",)), + ] + assert found[0].top == Decimal("0.0001") and found[0].unit == "mole/liter" + assert found[0].concentration(7) == Decimal("0.00000078125") + merged = parallelize(found) + assert len(merged) == 1 + assert merged[0].axis == "column" and merged[0].width == 4 + assert merged[0].levels[0] == ("A12", "B12", "C12", "D12") + assert merged[0].zero_wells == ("A4", "B4", "C4", "D4") + assert find_serial_dilutions(design, "Sal") == () + assert find_serial_dilutions(design, "Van", axis="column") == () + scattered = find_serial_dilutions(design, "Van", axis="set") + assert {(c.steps, c.width) for c in scattered} == {(8, 1)} + assert len(scattered) == 4 + with pytest.raises(ValueError, match="single-width row"): + parallelize(merged) + + +def test_detection_tolerates_rounded_ratios_and_requires_min_steps(): + sevenths = [ + Decimal("14.2857142857143"), + Decimal("7.14285714285714"), + Decimal("3.57142857142857"), + ] + design = PlateDesign.build( + "p", + final_volume=200 * uL, + wells=[ + well_target(f"A{i + 1}", concentrations={"Sal": v * uM, "Van": 0 * uM}) + for i, v in enumerate(sevenths) + ] + + [well_target("A4", concentrations={"Sal": 1 * uM, "Van": 5 * uM})], + ) + (candidate,) = find_serial_dilutions(design, "Sal") + assert candidate.fold == Decimal(2) and candidate.steps == 3 + assert candidate.levels == (("A1",), ("A2",), ("A3",)) + assert find_serial_dilutions(design, "Sal", min_steps=4) == () + pair = PlateDesign.build( + "p", + final_volume=200 * uL, + wells=[ + well_target("B5", concentrations={"Van": 20 * uM}), + well_target("B6", concentrations={"Van": 100 * uM}), + ], + ) + assert find_serial_dilutions(pair, "Van") == () + (five_fold,) = find_serial_dilutions(pair, "Van", min_steps=2) + assert five_fold.fold == Decimal(5) and five_fold.levels == (("B6",), ("B5",)) + + +def test_replicate_groups_ignore_material(): + groups = find_replicate_groups(gradient_design()) + assert len(groups) == 8 + assert all(len(g.wells) == 4 for g in groups) + assert {g.materials for g in groups} == {("strain / p1",) * 2 + ("strain / p2",) * 2} + + +def test_serial_dilution_arithmetic_and_concentrate_factor(): + (candidate,) = parallelize(find_serial_dilutions(gradient_design(), "Van")) + with pytest.raises(ValueError, match="use concentrate >= 1.12"): + plan_serial_dilution( + candidate, stock_concentration=1000 * uM, final_volume=200 * uL, capacity=360 * uL + ) + plan = plan_serial_dilution( + candidate, + stock_concentration=1000 * uM, + final_volume=200 * uL, + capacity=360 * uL, + reserved=10 * uL, + concentrate=Decimal(2), + ) + assert (plan.gradient_volume_ul, plan.transfer_volume_ul, plan.peak_volume_ul) == ( + 100, + 100, + 200, + ) + assert plan.top_stock_ul == 40 and plan.top_diluent_ul == 160 + assert plan.moves == 8 * 4 + with pytest.raises(ValueError, match="exceeds the stock"): + plan_serial_dilution( + candidate, + stock_concentration=100 * uM, + final_volume=200 * uL, + capacity=360 * uL, + concentrate=Decimal(2), + ) + with pytest.raises(ValueError, match="later additions"): + plan_serial_dilution( + candidate, + stock_concentration=1000 * uM, + final_volume=200 * uL, + capacity=360 * uL, + reserved=150 * uL, + concentrate=Decimal(2), + ) + + +def test_recorded_gradient_leaves_every_well_at_the_gradient_volume(): + design = gradient_design(zero=True) + (candidate,) = parallelize(find_serial_dilutions(design, "Van")) + plan = plan_serial_dilution( + candidate, + stock_concentration=1000 * uM, + final_volume=200 * uL, + capacity=360 * uL, + concentrate=Decimal(2), + ) + p = Protocol("gradient") + plate = p.plate("cultures", capacity=360 * uL) + stock = p.container("van", contents="Van 1000 uM", volume=1000 * uL, capacity=1500 * uL) + medium = p.container("medium", contents="medium", volume=15000 * uL, capacity=15000 * uL) + waste = p.container("waste", capacity=15000 * uL) + record_serial_dilution(p, plan, plate=plate, stock=stock, diluent=medium, waste=waste) + final = dict(compile(p, to=None).final_volumes) + for well in (*candidate.wells, *candidate.zero_wells): + assert final[Location("cultures", well)] == 100 + assert final[Location("waste", "A1")] == 400 + assert final[Location("van", "A1")] == 1000 - 4 * 40 + moves = [s for s in p.steps if isinstance(s, Transfer)] + assert len(moves) == 8 * 4 + assert {s.volume for s in moves} == {Decimal(100)} + mixes = [s for s in p.steps if isinstance(s, Mix)] + assert len(mixes) == 8 * 4 and all(m.volume == 100 and m.cycles == 3 for m in mixes) + assert isinstance(p.steps[0], Distribute) and p.steps[0].volume == 160 + assert isinstance(p.steps[2], Distribute) and p.steps[2].volume == 40 + + +def test_premix_scales_components_and_shares_one_portion(): + design = gradient_design() + group = next(g for g in find_replicate_groups(design) if "A12" in g.wells) + p = Protocol("premix") + plate = p.plate("cultures", capacity=360 * uL) + tubes = p.plate("tubes", shape=(4, 6), capacity=1500 * uL) + medium = p.container("medium", contents="medium", volume=15000 * uL, capacity=15000 * uL) + tmp = p.container("tmp", contents="TMP", volume=1000 * uL, capacity=1500 * uL) + plan = plan_premix( + group, + [(medium, 146 * uL, None), (tmp, 2 * uL, None)], + tube_capacity=p.capacity(tubes["A1"]), + ) + assert plan.portion_ul == 148 and plan.total_ul == Decimal("651.2") + assert plan.component_volume(plan.components[1]) == Decimal("8.8") + record_premix(p, plan, tube=tubes["A1"], plate=plate) + final = dict(compile(p, to=None).final_volumes) + assert all(final[Location("cultures", w)] == 148 for w in group.wells) + assert final[Location("tubes", "A1")] == Decimal("651.2") - 4 * 148 + with pytest.raises(ValueError, match="exceeds the 1500"): + plan_premix(group, [(medium, 400 * uL, None)], tube_capacity=1500 * uL) + + +def test_arrange_reproduces_a_row_wise_gradient_layout_and_reports_overflow(): + requirements = Requirements( + name="cultures", + final_volume=200 * uL, + materials=("strain / p1", "strain / p2"), + conditions=( + ConditionSpec(label="Sal 10", concentrations={"Sal": 10 * uM, "TMP": 3 * UG_ML}), + ConditionSpec(label="Sal 25", concentrations={"Sal": 25 * uM, "TMP": 3 * UG_ML}), + ), + gradient=GradientSpec(solute="Van", top=100 * uM, fold=Decimal(2), steps=8), + controls=(ControlSpec(label="blank", concentrations={"Van": 0 * uM, "Sal": 0 * uM}),), + ) + assert requirements.well_count == 2 * 2 * 8 + 2 + arrangement = arrange(requirements) + design = arrangement.design + assert design["A12"].concentration("Van").magnitude == Decimal("0.0001") + assert design["A5"].concentration("Van").magnitude == Decimal("0.00000078125") + assert design["B12"].material == "strain / p1" + assert design["B12"].concentration("Sal").magnitude == Decimal("0.000025") + assert design["C12"].material == "strain / p2" + assert {w.well for w in design.wells if w.concentration("TMP") is None} == {"A1", "B1"} + assert arrangement.rows[:2] == (("A", "strain / p1", "Sal 10"), ("B", "strain / p1", "Sal 25")) + assert len(arrangement.unused_wells) == 96 - requirements.well_count + merged = parallelize(find_serial_dilutions(design, "Van")) + assert [(c.width, c.steps) for c in merged] == [(4, 8)] + with pytest.raises(ValueError, match=r"\(32 over\)"): + arrange( + Requirements( + name="too many", + final_volume=200 * uL, + materials=tuple(f"m{i}" for i in range(8)), + conditions=requirements.conditions, + gradient=requirements.gradient, + ) + ) + with pytest.raises(ValueError, match="fixes Van"): + Requirements( + name="x", + final_volume=200 * uL, + materials=("m",), + conditions=(ConditionSpec(label="c", concentrations={"Van": 1 * uM}),), + gradient=requirements.gradient, + ) + with pytest.raises(ValueError, match="below 2"): + GradientSpec(solute="Van", top=1 * uM, fold=Decimal("1.5"), steps=3) + + +def _sources(p: Protocol): + reagents = p.plate("reagents", shape=(1, 12), capacity=15000 * uL, dead_volume=500 * uL) + plate = p.plate("cultures", capacity=360 * uL) + medium = p.container( + "medium", contents="medium", volume=15000 * uL, capacity=15000 * uL, dead_volume=500 * uL + ) + waste = p.container("waste", capacity=15000 * uL) + p.load(reagents["A1"], "Van 100 uM", volume=1500 * uL) + p.load(reagents["A2"], "Van 1000 uM", volume=1000 * uL) + p.load(reagents["A3"], "Sal 100 uM", volume=3000 * uL) + p.load(reagents["A4"], "TMP 300 ug/mL in DMSO", volume=1000 * uL) + p.load(reagents["A5"], "DMSO", volume=1000 * uL) + p.load(reagents["A6"], "strain / p1", volume=1000 * uL) + p.load(reagents["A7"], "strain / p2", volume=1000 * uL) + stocks = ( + Stock(solute="Van", concentration=100 * uM, source=reagents["A1"], max_target=25 * uM), + Stock(solute="Van", concentration=1000 * uM, source=reagents["A2"], max_target=200 * uM), + Stock(solute="Sal", concentration=100 * uM, source=reagents["A3"]), + Stock( + solute="TMP", + concentration=300 * UG_ML, + source=reagents["A4"], + vehicle_fraction=Decimal(1), + ), + ) + inocula = {"strain / p1": reagents["A6"], "strain / p2": reagents["A7"]} + return plate, medium, waste, reagents["A5"], stocks, inocula + + +def _settings(**changes): + base = dict( + final_volume=200 * uL, + inoculum_volume=10 * uL, + vehicle_fraction=Decimal("0.02"), + ) + return Settings(**(base | changes)) + + +@pytest.mark.parametrize("strategy", [Strategy.DIRECT, Strategy.AUTO, Strategy.SERIAL]) +def test_assemble_reaches_the_design_with_every_strategy(strategy): + design = gradient_design(zero=True) + p = Protocol("assemble") + plate, medium, waste, vehicle, stocks, inocula = _sources(p) + report = assemble( + p, + design, + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + settings=_settings(strategy=strategy), + vehicle=vehicle, + waste=waste, + ) + final = dict(compile(p, to=None).final_volumes) + assert all(final[Location("cultures", w.well)] == 200 for w in design.wells) + van_moves = [ + s + for s in p.steps + if isinstance(s, (Transfer, Distribute)) + and s.source in {Location("reagents", "A1"), Location("reagents", "A2")} + ] + if strategy is Strategy.DIRECT: + assert report.gradients == () + assert min(s.volume for s in van_moves) == Decimal("1.5625") + assert final[Location("waste", "A1")] == 0 + else: + assert [(g.candidate.width, g.candidate.steps) for g in report.gradients] == [(4, 8)] + assert min(s.volume for s in van_moves) == 40 + assert final[Location("waste", "A1")] == 400 + plans = {w.target.well: w for w in report.wells} + assert plans["A12"].gradient_ul == 100 and plans["A4"].gradient_ul == 100 + assert plans["A12"].medium_ul == 200 - 10 - 100 - 20 - 2 - 2 + assert all(s.solute != "Van" for s, _ in plans["A12"].doses) + assert report.skipped_gradients == () + + +def test_assemble_premixes_replicates_and_raises_on_missing_resources(): + design = gradient_design() + p = Protocol("premix") + plate, medium, waste, vehicle, stocks, inocula = _sources(p) + tubes = p.plate("tubes", shape=(4, 6), capacity=1500 * uL) + report = assemble( + p, + design, + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + settings=_settings(strategy=Strategy.DIRECT, premix_min_group=4), + vehicle=vehicle, + waste=waste, + tubes=[tubes[w] for w in tubes.wells], + ) + assert len(report.premixes) == 8 and all(w.premixed for w in report.wells) + final = dict(compile(p, to=None).final_volumes) + assert all(final[Location("cultures", w.well)] == 200 for w in design.wells) + liquid = [s.volume for s in p.steps if isinstance(s, (Transfer, Distribute, Mix))] + assert min(liquid) == Decimal("6.875") # 4 wells x 1.5625 uL x 1.1 overage + with pytest.raises(ValueError, match="more tubes"): + q = Protocol("few tubes") + plate, medium, waste, vehicle, stocks, inocula = _sources(q) + assemble( + q, + design, + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + settings=_settings(premix_min_group=4), + vehicle=vehicle, + waste=waste, + tubes=[], + ) + with pytest.raises(ValueError, match="waste container"): + q = Protocol("no waste") + plate, medium, _, vehicle, stocks, inocula = _sources(q) + assemble( + q, + design, + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + settings=_settings(), + vehicle=vehicle, + ) + with pytest.raises(ValueError, match="No serial dilution gradient"): + q = Protocol("flat") + plate, medium, waste, vehicle, stocks, inocula = _sources(q) + flat = PlateDesign.build( + "cultures", + final_volume=200 * uL, + wells=[well_target("A1", material="strain / p1", concentrations={"Van": 1 * uM})], + ) + assemble( + q, + flat, + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + settings=_settings(strategy=Strategy.SERIAL), + vehicle=vehicle, + waste=waste, + ) + with pytest.raises(ValueError, match="No inoculum source"): + q = Protocol("missing") + plate, medium, waste, vehicle, stocks, _ = _sources(q) + assemble( + q, + design, + plate=plate, + stocks=stocks, + medium=medium, + inocula={}, + settings=_settings(), + vehicle=vehicle, + waste=waste, + ) + + +def test_auto_skips_infeasible_gradients_and_serial_reports_them(): + design = gradient_design() + for strategy in (Strategy.AUTO, Strategy.SERIAL): + p = Protocol("shallow") + plate, medium, waste, vehicle, stocks, inocula = _sources(p) + kwargs = dict( + plate=plate, + stocks=stocks, + medium=medium, + inocula=inocula, + vehicle=vehicle, + waste=waste, + settings=_settings(strategy=strategy, concentrate=Decimal(1)), + ) + if strategy is Strategy.SERIAL: + with pytest.raises(ValueError, match="Peak volume 400"): + assemble(p, design, **kwargs) + else: + report = assemble(p, design, **kwargs) + assert report.gradients == () + assert [reason[:16] for _, reason in report.skipped_gradients] == ["Peak volume 400 "] + compile(p, to=None) From a1f074d6b359dac3544ef71c1c7f7aee1b2089d4 Mon Sep 17 00:00:00 2001 From: Mike Arpaia Date: Thu, 5 Nov 2026 23:23:10 +0000 Subject: [PATCH 2/9] Record pipetting advisories and trusted volume floors 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. --- CHANGELOG.md | 1 + docs/configuration.md | 2 +- docs/plates.md | 26 ++++ docs/worksheet-ui.md | 4 +- examples/concentration_series/__main__.py | 15 ++ examples/concentration_series/config.toml | 3 + src/lab/compiler.py | 19 ++- src/lab/config.py | 2 + src/lab/diagnostics.py | 99 +++++++++++++ src/lab/documents/assets/worksheet.css | 5 +- src/lab/documents/models.py | 9 ++ src/lab/documents/prepare.py | 15 ++ .../templates/sections/advisories.html | 20 +++ src/lab/documents/templates/worksheet.html | 2 + src/lab/limits.py | 86 +++++++++++ src/lab/model.py | 4 + src/lab/plates/__init__.py | 2 + src/lab/plates/advice.py | 86 +++++++++++ src/lab/targets/manual.py | 9 +- src/lab/targets/opentrons.py | 44 +++--- src/lab/targets/star.py | 9 ++ tests/test_diagnostics.py | 139 ++++++++++++++++++ 22 files changed, 572 insertions(+), 29 deletions(-) create mode 100644 src/lab/diagnostics.py create mode 100644 src/lab/documents/templates/sections/advisories.html create mode 100644 src/lab/limits.py create mode 100644 src/lab/plates/advice.py create mode 100644 tests/test_diagnostics.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 6dc97c1..dac4e78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,7 @@ - `lab.plates` describes a plate by its intended end state. `PlateDesign` and `WellTarget` hold per-well materials and solute concentrations; `find_serial_dilutions()` and `parallelize()` detect geometric gradients, `find_replicate_groups()` identical chemistry; `plan_serial_dilution()` and `record_serial_dilution()` build a gradient at a chosen concentrate factor with the arithmetic documented in `docs/plates.md`; `plan_premix()` and `record_premix()` prepare replicate portions once; `arrange()` lays out a plate from `Requirements`; `assemble()` prepares a design from declared stocks, medium, vehicle, and inocula under a `Strategy` of direct, serial, or automatic dosing and reports its decisions. - `lab.config.PlateDesignConfig` and `PreparationConfig` are the typed JSON and TOML forms of a design and of the preparation settings. `lab.plugins.lmsf` reads and writes the LMSF destination CSV as a view of a design; the core package does not depend on that format. - `Protocol.capacity()` returns the declared capacity of a plate or well. `lab.uM` and `lab.mM` are exported molar units. +- `compile(..., warn_below=, resolution=)` records advisory `Diagnostic`s on `Compilation.diagnostics`, in `plan.json`, and in a worksheet Advisories section: liquid steps below a head's trusted floor or the lab's own `warn_below`, and volumes that cannot be dialed at the given resolution. `lab.limits.PipettingLimits` describes each head's range and trusted floor; every `TargetPlan` lists its heads, and `Manual(pipettes=...)` takes a bench set. `lab.plates.advise_design()` gives the same advice for a design before any protocol exists. Hard limits remain `CompileError`s. ### Changed behavior diff --git a/docs/configuration.md b/docs/configuration.md index c825b06..4acf1e8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -48,4 +48,4 @@ For applications that do not use Pydantic, `lab.units.parse_quantity(value, unit ## Plate designs and preparation settings -`PlateDesignConfig` is the typed form of a [`lab.plates.PlateDesign`](plates.md): a name, an optional shape, the final volume, and `wells`, each with an optional `material` and a `concentrations` table of unit-bearing strings. `to_design()` builds the Lab object. `PreparationConfig` carries the `strategy` (`direct`, `serial`, or `auto`), `concentrate`, `serial_min_steps`, and the optional premix settings that `lab.plates.Settings` consumes. The concentration-series configuration uses `PreparationConfig` as its `[preparation]` table. +`PlateDesignConfig` is the typed form of a [`lab.plates.PlateDesign`](plates.md): a name, an optional shape, the final volume, and `wells`, each with an optional `material` and a `concentrations` table of unit-bearing strings. `to_design()` builds the Lab object. `PreparationConfig` carries the `strategy` (`direct`, `serial`, or `auto`), `concentrate`, `serial_min_steps`, the optional premix settings that `lab.plates.Settings` consumes, and the `warn_below` and `resolution` volumes passed to `compile()` for advisories. The concentration-series configuration uses `PreparationConfig` as its `[preparation]` table. diff --git a/docs/plates.md b/docs/plates.md index 226e0f7..7538ca3 100644 --- a/docs/plates.md +++ b/docs/plates.md @@ -190,6 +190,32 @@ target as the least concentrated stock whose `max_target` covers it. The recipe vehicle fraction against vehicle carried by stocks, fills the remainder with medium, then inoculates and mixes. Every balance is checked; a negative one is a `ValueError` naming the well. +## Advisories + +Hard limits stay errors: a volume no head can pipette or an overflowing well raises +`CompileError`. Everything that compiles but deserves attention is a `Diagnostic` on +`Compilation.diagnostics`, in `plan.json`, and in the worksheet's Advisories section: + +```python +bundle = compile(p, to=None, warn_below=2 * uL, resolution=Decimal("0.1") * uL) +for finding in bundle.diagnostics: + finding.severity, finding.code, finding.message, finding.locations, finding.step_index +``` + +Each target reports its heads as `lab.limits.PipettingLimits`: the vendor range plus the floor at +which the lab trusts the head. The Opentrons P20 is trusted from 2 µL rather than its 1 µL +minimum, the P300 across its range, the Flex 1000 from 50 µL; a STAR channel's declared minimum +is its floor; the manual target assumes a conventional P2, P10, P20, P200, P1000 set +(`Manual(pipettes=...)` replaces it). `warn_below` raises every floor to the lab's own value. +A step below the floor of the smallest head that covers it, or outside every head, is a +`volume-below-trusted-minimum` warning; `resolution` adds `volume-resolution` notes for volumes +that cannot be dialed at that step. + +Before a protocol exists, `advise_design(design, stocks, limits, warn_below=...)` reports the +direct dose each well would need from the given stock concentrations, the gradients +(`serial-dilution-available`) and replicate groups (`premix-available`) that would avoid small +doses. It is the design-time view that a layout tool shows while a plate is being edited. + ## Format plugins Sheet formats are not core concepts. `lab.plugins.lmsf` reads and writes the LMSF destination diff --git a/docs/worksheet-ui.md b/docs/worksheet-ui.md index 9bf796c..1262da6 100644 --- a/docs/worksheet-ui.md +++ b/docs/worksheet-ui.md @@ -11,7 +11,7 @@ The implementation lives in `src/lab/documents/`: | `flow.py` | Calculate the numeric phases and coordinates of idealized flow profiles. | | `preparation.py` | Turn the compiler's volume trace into plate geometry and a snapshot after each operation. | | `templates/worksheet.html` | Compose the page and embed its assets. | -| `templates/sections/` | Materials, preparation preview, ordered procedure, final volumes, and reference details. | +| `templates/sections/` | Advisories, materials, preparation preview, ordered procedure, final volumes, and reference details. | | `templates/components/` | Reusable references, tables, headings, fields, detail cards, plate maps, inspector, and flow charts. | | `assets/` | Page and component styles, responsive and print rules, and interactive components. | | `render.py` | Configure Jinja, load packaged assets in a fixed order, and render the page. | @@ -41,6 +41,8 @@ The maps represent logical row and column coordinates. They do not infer robot t For the Manual target, a distribution represents a separate measured aspiration and complete dispense for each destination. The animation returns to the source empty between wells and the flow profile uses the same alternating aspiration/dispense phases. The grouped procedure step and its total delivered volumes remain unchanged. This avoids depicting repeated partial strokes from a single large load with an ordinary manual micropipette. +The Advisories section lists `Compilation.diagnostics` with links to the procedure steps and wells they name; it is omitted when there are none. + The overview counts one fresh tip for each `Transfer`, `Distribute`, or `Mix`, matching the current target policy. A distribution reuses its tip across its destinations. The concentration-series recipe explicitly groups identical source/dose additions into distributions; the document renderer does not reorder operations. Each preview change publishes `lab:previewchange` inside its worksheet. `` uses that event to display the selected state's amount in reagent lists and well-detail cards, including cloned inspector cards. The preview also exposes `currentFrame` so a newly connected volume display can read the selected snapshot. This keeps preview-specific behavior out of the inspector. Procedure step numbers link back to the matching snapshot. diff --git a/examples/concentration_series/__main__.py b/examples/concentration_series/__main__.py index ff6b62e..4e8e775 100644 --- a/examples/concentration_series/__main__.py +++ b/examples/concentration_series/__main__.py @@ -8,6 +8,7 @@ import argparse import hashlib +import sys import tomllib from pathlib import Path @@ -43,6 +44,11 @@ def main() -> None: choices=("direct", "serial", "auto"), help="Override preparation.strategy from the configuration", ) + parser.add_argument( + "--warn-below", + help='Smallest volume you trust any pipette to deliver, e.g. "2 uL"; ' + "overrides preparation.warn_below", + ) parser.add_argument("--out") args = parser.parse_args() try: @@ -50,6 +56,8 @@ def main() -> None: raw = tomllib.load(stream) if args.strategy is not None: raw.setdefault("preparation", {})["strategy"] = args.strategy + if args.warn_below is not None: + raw.setdefault("preparation", {})["warn_below"] = args.warn_below config = ProtocolConfig.model_validate(raw) csv_bytes = args.csv.read_bytes() design = select( @@ -77,8 +85,15 @@ def main() -> None: deck=config.deck if handler else None, liquid_handler=handler, to=args.out or f"build/concentration_series/csv/{args.target}", + warn_below=config.preparation.warn_below, + resolution=config.preparation.resolution, ) print(bundle.directory) + for diagnostic in bundle.diagnostics: + step = ( + f" (step {diagnostic.step_index + 1})" if diagnostic.step_index is not None else "" + ) + print(f"{diagnostic.severity.value}{step}: {diagnostic.message}", file=sys.stderr) except (ValueError, TypeError, KeyError, OSError) as exc: parser.error(str(exc)) diff --git a/examples/concentration_series/config.toml b/examples/concentration_series/config.toml index b1b6b24..c8cc070 100644 --- a/examples/concentration_series/config.toml +++ b/examples/concentration_series/config.toml @@ -18,10 +18,13 @@ solute_and_vehicle_free_medium_and_cultures = true # every well straight from its stock. The gradient is built at `concentrate` times the # final concentration so the mixing volume fits the well, then topped up with the # constant additions. Runs shorter than serial_min_steps are dosed directly. +# warn_below is the smallest volume this lab trusts any pipette to deliver; steps under +# it (or under a head's own trusted floor) are listed as advisories, not errors. [preparation] strategy = "auto" concentrate = "2" serial_min_steps = 4 +warn_below = "2 uL" # Portable classes specify these two rates only. Other robot settings and # calibration retain SDK defaults; the numbers below need instrument validation. diff --git a/src/lab/compiler.py b/src/lab/compiler.py index a9d71bb..a171fdf 100644 --- a/src/lab/compiler.py +++ b/src/lab/compiler.py @@ -12,12 +12,14 @@ import lab.documents as documents from lab._version import __version__ from lab.deck import Deck +from lab.diagnostics import Diagnostic, advise from lab.model import Distribute, Mix, RecordedProtocol, TargetPlan, Transfer, encode from lab.protocol import Protocol from lab.samples import Location, OutputManifest from lab.targets.liquid_handler import LiquidHandler from lab.targets.lower import lower_deck from lab.targets.manual import Manual +from lab.units import magnitude from lab.validation import CompileError, logical_bindings, validate @@ -35,6 +37,7 @@ class Compilation: target: TargetPlan final_volumes: tuple[tuple[Location, Decimal], ...] directory: Path | None = None + diagnostics: tuple[Diagnostic, ...] = () @property def manifest(self) -> OutputManifest: @@ -59,6 +62,7 @@ def plan_json(self) -> str: {"location": encode(location), "volume": encode(volume)} for location, volume in self.final_volumes ], + "diagnostics": encode(self.diagnostics), "source_sha256": ( hashlib.sha256(self.target.source.encode()).hexdigest() if self.target.source is not None @@ -140,6 +144,8 @@ def compile( deck: Deck | None = None, liquid_handler: LiquidHandler | None = None, to: str | Path | None | _DefaultOutput = _DEFAULT_OUTPUT, + warn_below: Any = None, + resolution: Any = None, ) -> Compilation: """Snapshot and compile a protocol for a manual document or a robot. @@ -147,6 +153,11 @@ def compile( ``deck`` with a liquid handler for a robot, or omit both for a manual document. Bundles are written to ``~/.lab///``; ``LAB_HOME`` changes that root, ``to`` selects a directory, and ``to=None`` skips writing. + + ``warn_below`` is the smallest volume the lab trusts any head to deliver; liquid steps + under it, or under a head's own trusted floor, appear in ``Compilation.diagnostics`` + without failing compilation. ``resolution`` adds a note for volumes that cannot be + dialed on a pipette with that step size. """ if not isinstance(protocol, Protocol): raise TypeError("Compile a Protocol; use an experiment builder to turn designs into one.") @@ -196,7 +207,13 @@ def compile( configuration["lab_deck"] = encode(authored_deck) prepared = replace(prepared, configuration_json=json.dumps(configuration, sort_keys=True)) volumes = validate(recorded, prepared.bindings) - compilation = Compilation(recorded, prepared, tuple(volumes.items())) + diagnostics = advise( + recorded, + prepared.limits, + warn_below=magnitude(warn_below, "microliter") if warn_below is not None else None, + resolution=magnitude(resolution, "microliter") if resolution is not None else None, + ) + compilation = Compilation(recorded, prepared, tuple(volumes.items()), diagnostics=diagnostics) directory = _output_directory(compilation, to) if directory is not None: _write_output(directory, compilation.files) diff --git a/src/lab/config.py b/src/lab/config.py index 8f910e8..098138c 100644 --- a/src/lab/config.py +++ b/src/lab/config.py @@ -149,3 +149,5 @@ class PreparationConfig(ConfigModel): serial_min_steps: Annotated[int, Field(strict=True, ge=2)] = 4 premix_min_group: Annotated[int, Field(strict=True, ge=2)] | None = None premix_overage: Annotated[Decimal, Field(ge=1, allow_inf_nan=False)] = Decimal("1.1") + warn_below: Volume | None = None + resolution: Volume | None = None diff --git a/src/lab/diagnostics.py b/src/lab/diagnostics.py new file mode 100644 index 0000000..1842fb9 --- /dev/null +++ b/src/lab/diagnostics.py @@ -0,0 +1,99 @@ +"""Advisory findings that compilation records without rejecting a protocol. + +Hard limits stay errors: a volume no head can pipette or an overflowing well raises +``CompileError``. Diagnostics describe what compiles but deserves attention, such as a dose +below the floor at which a head's accuracy is trusted. +""" + +from dataclasses import dataclass +from decimal import Decimal +from enum import Enum + +from lab.limits import PipettingLimits, smallest_covering +from lab.model import Distribute, Mix, Origin, RecordedProtocol, Transfer +from lab.samples import Location +from lab.units import number + + +class Severity(Enum): + INFO = "info" + WARNING = "warning" + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Diagnostic: + """One finding; ``step_index`` is zero-based when the finding names a recorded step.""" + + severity: Severity + code: str + message: str + locations: tuple[Location, ...] = () + step_index: int | None = None + origin: Origin | None = None + + +Diagnostics = tuple[Diagnostic, ...] + +BELOW_TRUSTED_MINIMUM = "volume-below-trusted-minimum" +VOLUME_RESOLUTION = "volume-resolution" + + +def advise( + protocol: RecordedProtocol, + limits: tuple[PipettingLimits, ...], + *, + warn_below: Decimal | None = None, + resolution: Decimal | None = None, +) -> Diagnostics: + """Flag liquid steps below the trusted floor of the smallest head that covers them. + + ``warn_below`` raises every head's floor to at least that volume. ``resolution`` adds an + informational finding for volumes that are not a multiple of the smallest dialable step. + With no limits at all, every liquid step is compared against ``warn_below`` alone. + """ + found: list[Diagnostic] = [] + for index, step in enumerate(protocol.steps): + if not isinstance(step, (Transfer, Distribute, Mix)): + continue + if isinstance(step, Transfer): + where: tuple[Location, ...] = (step.destination,) + elif isinstance(step, Distribute): + where = step.destinations + else: + where = (step.location,) + head = smallest_covering(limits, step.volume) + floor = max( + head.trusted_minimum_ul if head is not None else Decimal(0), + warn_below if warn_below is not None else Decimal(0), + ) + if (head is None and limits) or step.volume < floor: + label = head.label if head is not None else "any configured pipette" + detail = ( + f"below the trusted {number(floor)} µL floor of {label}" + if head is not None + else f"outside the range of {label}" + ) + found.append( + Diagnostic( + severity=Severity.WARNING, + code=BELOW_TRUSTED_MINIMUM, + message=f"{number(step.volume)} µL is {detail}; " + "consider a serial dilution or a premix.", + locations=where, + step_index=index, + origin=step.origin, + ) + ) + if resolution is not None and step.volume.remainder_near(resolution) != 0: + found.append( + Diagnostic( + severity=Severity.INFO, + code=VOLUME_RESOLUTION, + message=f"{number(step.volume)} µL cannot be dialed at " + f"{number(resolution)} µL resolution; the compiler does not round doses.", + locations=where, + step_index=index, + origin=step.origin, + ) + ) + return tuple(found) diff --git a/src/lab/documents/assets/worksheet.css b/src/lab/documents/assets/worksheet.css index 2dfd1fd..7b29032 100644 --- a/src/lab/documents/assets/worksheet.css +++ b/src/lab/documents/assets/worksheet.css @@ -18,7 +18,7 @@ a:focus-visible, summary:focus-visible, .table-scroll:focus-visible { outline: 2 .brand { font-weight: 750; color: var(--accent); } h1 { margin: 24px 0 12px; color: #183c36; font-size: clamp(26px, 3.5vw, 40px); font-weight: 650; line-height: 1.15; letter-spacing: -.035em; text-wrap: balance; overflow-wrap: anywhere; } .description { max-width: 78ch; margin: 0; color: var(--muted); font-size: 15px; white-space: pre-wrap; overflow-wrap: anywhere; } -.overview { display: grid; grid-template-columns: repeat(5, 1fr); gap: 20px; margin: 28px 0 24px; } +.overview { display: grid; grid-template-columns: repeat(auto-fit, minmax(150px, 1fr)); gap: 20px; margin: 28px 0 24px; } .overview > div { border-left: 2px solid var(--line); padding-left: 14px; } dt { font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: var(--muted); } dd { margin: 4px 0 0; font-size: 24px; font-weight: 600; line-height: 1.2; overflow-wrap: anywhere; } @@ -65,6 +65,9 @@ small { display: block; color: var(--muted); font-size: 10px; line-height: 1.5; caption { text-align: left; padding: 0 0 10px; font-weight: 650; font-size: 14px; overflow-wrap: anywhere; } .volume-grid th, .volume-grid td { padding-block: 7px; } .setup ul { font-size: 13px; padding-left: 20px; } +.advisories td { vertical-align: top; padding-block: 7px; } +.advisory-warning td:first-child { color: var(--accent); font-weight: 600; text-transform: capitalize; } +.advisory-info td:first-child { color: var(--muted); text-transform: capitalize; } .setup li { margin-top: 8px; overflow-wrap: anywhere; } footer { border-top: 1px solid var(--line); padding-top: 24px; color: var(--muted); font-size: 12px; } footer h2 { font-size: 15px; margin-bottom: 12px; } diff --git a/src/lab/documents/models.py b/src/lab/documents/models.py index a86fcc4..97fb262 100644 --- a/src/lab/documents/models.py +++ b/src/lab/documents/models.py @@ -8,6 +8,7 @@ from decimal import Decimal from typing import TypeAlias +from lab.diagnostics import Diagnostic from lab.documents.flow import FlowProfile from lab.model import Fill, RecordedProtocol, Resource, TargetPlan from lab.samples import Location, Sample @@ -122,6 +123,13 @@ class PreparationView: frames: tuple[PreparationFrame, ...] +@dataclass(frozen=True) +class AdvisoryRow: + diagnostic: Diagnostic + step_number: int | None + locations: tuple[Reference, ...] + + @dataclass(frozen=True) class Worksheet: protocol: RecordedProtocol @@ -134,3 +142,4 @@ class Worksheet: procedure: tuple[ProcedureRow, ...] liquid_classes: tuple[LiquidClassView, ...] preparation: PreparationView + advisories: tuple[AdvisoryRow, ...] = () diff --git a/src/lab/documents/prepare.py b/src/lab/documents/prepare.py index b6ad969..f1ccfc6 100644 --- a/src/lab/documents/prepare.py +++ b/src/lab/documents/prepare.py @@ -9,6 +9,7 @@ from lab.documents.descriptions import describe from lab.documents.flow import build_flow_profile from lab.documents.models import ( + AdvisoryRow, DetailFields, IncomingTransfer, LiquidClassView, @@ -245,4 +246,18 @@ def build_worksheet(compilation: compiler.Compilation) -> Worksheet: _liquid_class(ref, spec, p.steps, target) for spec, ref in classes.items() ), preparation=build_preparation(compilation, tuple(resources)), + advisories=tuple( + AdvisoryRow( + diagnostic=diagnostic, + step_number=diagnostic.step_index + 1 + if diagnostic.step_index is not None + else None, + locations=tuple( + locations[location] + for location in diagnostic.locations + if location in locations + ), + ) + for diagnostic in compilation.diagnostics + ), ) diff --git a/src/lab/documents/templates/sections/advisories.html b/src/lab/documents/templates/sections/advisories.html new file mode 100644 index 0000000..f7b205f --- /dev/null +++ b/src/lab/documents/templates/sections/advisories.html @@ -0,0 +1,20 @@ +{% from "components/ui.html" import reference %} +{% if document.advisories %} +
+

Advisories

+

Findings that compile but deserve attention. Hard limits are enforced during compilation and never appear here.

+ + + + {% for row in document.advisories %} + + + + + + + {% endfor %} + +
SeverityStepFindingWells
{{ row.diagnostic.severity.value }}{% if row.step_number is not none %}{{ "%02d"|format(row.step_number) }}{% endif %}{{ row.diagnostic.message }}{% for ref in row.locations %}{{ reference(ref) }}{% if not loop.last %}, {% endif %}{% endfor %}
+
+{% endif %} diff --git a/src/lab/documents/templates/worksheet.html b/src/lab/documents/templates/worksheet.html index 9f67b5e..45d55e5 100644 --- a/src/lab/documents/templates/worksheet.html +++ b/src/lab/documents/templates/worksheet.html @@ -19,6 +19,7 @@

{{ document.protocol.name }}

Fresh tips
{{ document.tip_count }}
Resources
{{ document.resources|length }}
Output samples
{{ document.protocol.output_sample_ids|length }}
+ {% if document.advisories %}{% endif %}