diff --git a/CHANGELOG.md b/CHANGELOG.md index fca1c70..0d31f5c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## Unreleased + +### Added + +- `lab.plates` describes a plate by its intended end state. `PlateDesign` and `WellTarget` hold per-well `Material` records (a name, or a strain and construct that name it, with an optional SBOL design) 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. + +- `Protocol.transfer()` and `mix()` accept sequences of wells and record `MultiTransfer` and `MultiMix` lane sets; `Plate.column()` returns a column in row order. Opentrons 8-channel heads (`PipetteModel.P20_MULTI_GEN2`, `P300_MULTI_GEN2`, `FLEX_8CHANNEL_50`, `FLEX_8CHANNEL_1000`, with `TipRackModel.FLEX_50_UL` and `FLEX_1000_UL`) run a full-column lane set in one stroke; STAR layouts configure up to eight `Channel`s and run lanes across them; single-channel heads and the manual target run lanes in turn. The worksheet lists lanes and animates them together. +- `TipPolicy` is recorded with a protocol (`Protocol(name, tip_policy=...)`) or overridden with `compile(..., tip_policy=...)`: fresh per step, reuse per source, or reuse while every destination's contents are contained in the source's. `Protocol.load(..., components=...)` declares what a source is made of; `lab.tips` numbers and counts tips, and `prewet()` records a pre-wetting stroke. Generated robot programs and `plan.json` carry the policy; the worksheet shows the resulting tip count. + +### 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, one more tip rack per robot layout, and eight STAR channels so gradient columns move in one stroke. Serial dilution levels are recorded as lane sets, so the example compiles to 342 steps under `auto`. + ## 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..55b0316 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` (a name, or a table with `name` and optional `strain`, `construct`, and `design`) 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, the `warn_below` and `resolution` volumes passed to `compile()` for advisories, and the `tip_policy` the protocol is recorded with. 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..0852dca --- /dev/null +++ b/docs/plates.md @@ -0,0 +1,285 @@ +# 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. + +A material is a `Material`: a display `name` plus optional `strain`, `construct` (a plasmid or +other genetic construct), and `design` (an SBOL design IRI). A material given a strain or +construct and no name is named by them, `"strain / construct"`, so `Material(strain="BL21", +construct="pA")` is called `BL21 / pA`. `well_target(material="plasmid-1")` accepts a bare +name and makes the record for you; two materials with the same name must be the same record. `design.materials` lists the distinct records by name and `design.material(name)` +looks one up. Nothing in the name is parsed: `lab.plugins.lmsf` builds its materials from the +sheet's strain and plasmid columns and reads them back from those attributes. +`lab.config.PlateDesignConfig` is the typed JSON or TOML form of a design for applications +installed with `lab-compiler[config]`; there a well's `material` is a name or a table with +`name`, `strain`, `construct`, and `design`. + +## 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. + +## Lanes and multichannel heads + +`Protocol.transfer()` and `mix()` accept sequences of wells. Lane `i` moves `source[i]` to +`destination[i]`; one source well feeds every lane; several lanes may share a destination such +as a waste trough. `Plate.column(n)` returns a column in row order, so a serial dilution step +reads as it is pipetted: + +```python +p.transfer(plate.column(12), plate.column(11), volume=100 * uL) +p.mix(plate.column(11), volume=100 * uL, cycles=3) +``` + +These record `MultiTransfer` and `MultiMix` steps. Volume accounting treats every lane +separately; the worksheet lists the lanes and animates them together. Targets specialize: + +| Target | Lane set that fills rows A–H of one column | Other lane sets | +| --- | --- | --- | +| Opentrons with an 8-channel head (`p300_multi_gen2`, `p20_multi_gen2`, `flex_8channel_50`, `flex_8channel_1000`) | One stroke addressed by the column's top well; the head draws from a matching column or one trough well and picks up a whole column of tips | A single-channel head runs the lanes in turn, with one tip for a shared source and a fresh tip per lane otherwise | +| Hamilton STAR with `n` configured `Channel`s | Up to `n` lanes per stroke on `use_channels=[0, …]`; alternating rows such as A/C/E/G are one stroke | Lanes are taken in groups of `n`; a shared trough is drawn lane by lane | +| Manual | "Transfer 100 µL along 8 lanes together from cultures column 12 (rows A–H) to column 11", for an 8-channel pipette | The lanes are listed | + +`record_serial_dilution()` records every level wider than one well as a lane set, so a gradient +across rows A/C/E/G is four lanes per step: one STAR stroke, or four single-channel moves on an +OT-2 whose 8-channel head cannot skip rows. + +## Tip policy + +`Protocol(name, tip_policy=...)` records when tips are replaced; `compile(..., tip_policy=...)` +overrides it. `TipPolicy.FRESH_PER_STEP` takes a new tip for every transfer, distribution, or +mix. `REUSE_PER_SOURCE` keeps a tip while consecutive steps draw from one source with one liquid +class. `REUSE_WHEN_CONTAINED` keeps a tip while every destination holds only substances the +source also holds, so nothing foreign is carried back into the source: medium may go into empty +wells on one tip, a first additive may follow it into those wells on one tip, but the first well +that already holds a second additive forces a fresh tip. Declare what a source is made of with +`load(..., components=("medium", "Van"))`; a fill without components is one component named by +the text it was loaded as. + +A pre-wetting stroke is `prewet(p, source, volume=...)`: a one-cycle mix at the source that +leaves the volume accounting unchanged and, under a reuse policy, keeps the tip for the moves +that follow. `assemble()` records one before the first move from each source when the protocol's +policy reuses tips. `lab.tips.assign_tips()` numbers the tips of a recorded protocol and +`tip_count()` counts them (a multichannel stroke counts one tip per lane); the worksheet and +`plan.json` report the policy and the count, and robot targets pick up and drop tips at the +numbered boundaries. + +## 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 +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/docs/worksheet-ui.md b/docs/worksheet-ui.md index 9bf796c..02fe6b3 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. | @@ -33,15 +33,17 @@ Autoescaping applies to every template, including attributes and SVG. Missing te Both components use light DOM, so the templates, stylesheet, browser accessibility tree, and print rules share the same markup. Each instance owns its state and removes listeners and observers when disconnected. -`` displays the logical resource grids and lets the reader play, step, or scrub through the procedure. It uses `volume_trace()` from the compiler's validator; JavaScript selects precomputed snapshots and does no volume accounting. A snapshot is the state after one complete protocol operation, including all destinations of a distribution. Mixes, waits, temperature operations, and operator instructions retain the recorded liquid volumes. Source and destination outlines identify transfers; a dashed outline identifies mixing and temperature operations. Filled well area is proportional to volume divided by the smaller of declared and bound capacities. +`` displays the logical resource grids and lets the reader play, step, or scrub through the procedure. It uses `volume_trace()` from the compiler's validator; JavaScript selects precomputed snapshots and does no volume accounting. A snapshot is the state after one complete protocol operation, including all destinations of a distribution or every lane of a lane set. Mixes, waits, temperature operations, and operator instructions retain the recorded liquid volumes. Source and destination outlines identify transfers; a dashed outline identifies mixing and temperature operations. Filled well area is proportional to volume divided by the smaller of declared and bound capacities. The maps represent logical row and column coordinates. They do not infer robot trajectories, physical deck geometry, tip use, mixing completeness, or chemical composition. Initial reagent labels and sample identities come directly from the protocol. Well details include physical bindings. Playback uses one continuous clock for the pipette, dispensing drops, and position slider, allowing more time for distributions and repeated mixes. Between operations, the empty pipette travels to the next source in a short transition. Pausing preserves the current position; scrubbing selects a fractional position within an operation, and keyboard arrows step through whole operations. Playback starts only on request and pauses when the preview leaves view, the tab is hidden, or the reader inspects a well. Reduced-motion mode disables fill and pipette animations. -`` draws directional paths between the rendered wells and animates a schematic pipette, aspiration, and dispensing drops. A distribution connects its source and ordered destinations; mixing repeats its recorded cycles in place. Temperature operations have no pipette motion. The component measures the actual displayed well positions, redraws on resize or plate scrolling, and leaves a static route available while paused or in reduced-motion mode. The animation illustrates the selected operation; the numeric snapshot remains explicitly labeled as its after-state. It is independent of hardware choreography and duration: a target may refill the tip between destinations. +`` draws directional paths between the rendered wells and animates a schematic pipette, aspiration, and dispensing drops. A distribution connects its source and ordered destinations; a lane set (`MultiTransfer`) connects each source to its own destination; mixing repeats its recorded cycles in place. Temperature operations have no pipette motion. The component measures the actual displayed well positions, redraws on resize or plate scrolling, and leaves a static route available while paused or in reduced-motion mode. The animation illustrates the selected operation; the numeric snapshot remains explicitly labeled as its after-state. It is independent of hardware choreography and duration: a target may refill the tip between destinations. 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 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. +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 tips with `lab.tips.tip_count()` under the protocol's recorded `TipPolicy`, which the robot targets follow; a distribution reuses its tip across its destinations and a lane set counts one tip per lane. 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 21a0383..4e8e775 100644 --- a/examples/concentration_series/__main__.py +++ b/examples/concentration_series/__main__.py @@ -2,25 +2,36 @@ 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 sys 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 +39,45 @@ 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( + "--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: 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 + 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() - 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( @@ -55,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 1bf54d5..2f33b8d 100644 --- a/examples/concentration_series/config.toml +++ b/examples/concentration_series/config.toml @@ -13,6 +13,23 @@ 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. +# 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. +# tip_policy: "fresh_per_step" takes a new tip for every operation; "reuse_when_contained" +# keeps a tip while every destination holds only what the source holds and pre-wets it first; +# "reuse_per_source" keeps a tip while consecutive operations draw from one source. +[preparation] +strategy = "auto" +concentrate = "2" +serial_min_steps = 4 +warn_below = "2 uL" +tip_policy = "fresh_per_step" + # 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 +58,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 +156,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 +167,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 +176,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 +188,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 +200,17 @@ 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. +# Eight independent channels with 300 uL tips; a gradient column moves in one stroke. +# The 1 uL minimum is a software demonstration limit, not a validated 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"] }, + { index = 1, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 2, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 3, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 4, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 5, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 6, min_volume_ul = "1", max_volume_ul = "300", tip_racks = ["star_tips", "star_tips_2", "star_tips_3", "star_tips_4", "star_tips_5"] }, + { index = 7, 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..c08b7b1 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 lmsf_material 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,126 @@ 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, + components=(config.medium.name,), + ) + diluent = None + if config.medium.diluent_volume is not None: + p.load( + media["A2"], + config.medium.name, + volume=config.medium.diluent_volume, + components=(config.medium.name,), ) - 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, + diluent = media["A2"] + waste = p.container("waste", capacity=15000 * uL) + p.load( + reagents[config.vehicle.well], + config.vehicle.name, + volume=config.vehicle.volume, + components=(config.vehicle.name,), + ) + 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, + components=(stock.solute, config.vehicle.name) + if stock.vehicle_fraction + else (stock.solute, config.medium.name), + ) + 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 = lmsf_material(culture.strain, culture.plasmid) + p.load( + reagents[culture.well], + material.name, + volume=culture.volume, + components=(config.medium.name, material.name), + ) + inocula[material.name] = reagents[culture.well] + culture_wells[material.name] = 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..2359075 100644 --- a/examples/concentration_series/protocol.py +++ b/examples/concentration_series/protocol.py @@ -1,165 +1,71 @@ -"""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.model import TipPolicy +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)}", + tip_policy=TipPolicy(config.preparation.tip_policy), ) - - # 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.name] 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.name}; " + + ", ".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/compiler.py b/src/lab/compiler.py index a9d71bb..de1842b 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.model import Distribute, Mix, RecordedProtocol, TargetPlan, Transfer, encode +from lab.diagnostics import Diagnostic, advise +from lab.model import LIQUID_STEPS, RecordedProtocol, TargetPlan, TipPolicy, 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,9 @@ 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, + tip_policy: TipPolicy | None = None, ) -> Compilation: """Snapshot and compile a protocol for a manual document or a robot. @@ -147,6 +154,12 @@ 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. ``tip_policy`` overrides the policy the + protocol was recorded with; targets pick up and drop tips accordingly. """ if not isinstance(protocol, Protocol): raise TypeError("Compile a Protocol; use an experiment builder to turn designs into one.") @@ -160,15 +173,17 @@ def compile( deck if deck is not None else target if target is not None else Manual() ) recorded = protocol.snapshot() + if tip_policy is not None: + if not isinstance(tip_policy, TipPolicy): + raise TypeError("Pass a TipPolicy member") + recorded = replace(recorded, tip_policy=tip_policy) authored_deck = hardware if isinstance(hardware, Deck) else None if isinstance(hardware, Deck): if not isinstance(liquid_handler, LiquidHandler): raise TypeError( "Pass liquid_handler=LiquidHandler.OT2, LiquidHandler.FLEX, or LiquidHandler.STAR." ) - liquid = tuple( - step.volume for step in recorded.steps if isinstance(step, (Transfer, Mix, Distribute)) - ) + liquid = tuple(step.volume for step in recorded.steps if isinstance(step, LIQUID_STEPS)) requirements = {container.id: container.labware for container in hardware.containers} for resource in recorded.resources: spec = requirements.get(resource.name) @@ -196,7 +211,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 4255a30..4346af2 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 Material, 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,79 @@ 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 MaterialConfig(ConfigModel): + """A named material with optional structure; a bare string is accepted as the name. + + The genetic construct is written as ``construct`` in configuration; the attribute is + named ``genetic_construct`` because pydantic reserves ``construct``. + """ + + model_config = ConfigDict( + extra="forbid", arbitrary_types_allowed=True, frozen=True, populate_by_name=True + ) + + name: NonemptyString + strain: NonemptyString | None = None + genetic_construct: NonemptyString | None = Field(default=None, alias="construct") + design: NonemptyString | None = None + + def to_material(self) -> Material: + return Material( + name=self.name, + strain=self.strain, + construct=self.genetic_construct, + design=self.design, + ) + + +class WellTargetConfig(ConfigModel): + """One well of a plate design: an optional material and solute concentrations.""" + + well: WellName + material: MaterialConfig | NonemptyString | None = None + concentrations: dict[NonemptyString, Concentration] + + def to_material(self) -> Material | None: + if isinstance(self.material, MaterialConfig): + return self.material.to_material() + return Material(name=self.material) if self.material else None + + +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.to_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") + warn_below: Volume | None = None + resolution: Volume | None = None + tip_policy: Literal["fresh_per_step", "reuse_per_source", "reuse_when_contained"] = ( + "fresh_per_step" + ) 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/preparation.js b/src/lab/documents/assets/preparation.js index 6bc6c4d..6d4d4ea 100644 --- a/src/lab/documents/assets/preparation.js +++ b/src/lab/documents/assets/preparation.js @@ -113,7 +113,7 @@ class PreparationPreview extends HTMLElement { const anchor = well.dataset.mapWell; const state = this.volumes.get(anchor); well.querySelector(".well-liquid").setAttribute("r", state.radius); - well.classList.toggle("is-source", anchor === frame.source); + well.classList.toggle("is-source", anchor === frame.source || (frame.sources || []).includes(anchor)); well.classList.toggle("is-destination", frame.destinations.includes(anchor)); well.classList.toggle("is-active", frame.active.includes(anchor)); const description = `${well.dataset.wellLabel} · ${state.volume} µL · ${label}`; diff --git a/src/lab/documents/assets/transfer-motion.js b/src/lab/documents/assets/transfer-motion.js index a4fc25b..737d5fe 100644 --- a/src/lab/documents/assets/transfer-motion.js +++ b/src/lab/documents/assets/transfer-motion.js @@ -64,7 +64,9 @@ class TransferMotion extends HTMLElement { geometry(frame) { const board = this.board.getBoundingClientRect(); - const anchors = frame.refill_between_destinations + const anchors = frame.lanes + ? frame.destinations.flatMap((destination, index) => [frame.sources[index], destination]) + : frame.refill_between_destinations ? frame.destinations.flatMap(destination => [frame.source, destination]) : frame.source ? [frame.source, ...frame.destinations] : frame.active; const points = anchors.map(anchor => this.point(anchor)); @@ -93,7 +95,9 @@ class TransferMotion extends HTMLElement { showFrame(frame, animate = false, origin = null) { this.stop(); this.frame = frame; - this.duration = Math.max(900, frame.refill_between_destinations + this.duration = Math.max(900, frame.lanes + ? 900 + : frame.refill_between_destinations ? frame.destinations.length * 900 : frame.source ? 250 + frame.destinations.length * 450 : frame.mix_cycles * 400); this.routes.replaceChildren(); @@ -109,7 +113,7 @@ class TransferMotion extends HTMLElement { const transitionDuration = animate && !this.reducedMotion.matches && distance > .5 ? Math.min(240, Math.max(100, distance / 3)) : 0; const paths = points.slice(1).map((point, index) => - this.route(points[index], point, frame.refill_between_destinations && index % 2 === 1)); + this.route(points[index], point, (frame.refill_between_destinations || frame.lanes) && index % 2 === 1)); const last = points.at(-1); this.pipette.style.transform = `translate(${last.x}px, ${last.y - 12}px)`; if (!animate || this.reducedMotion.matches) return; 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/descriptions.py b/src/lab/documents/descriptions.py index 4c58fe1..7275efe 100644 --- a/src/lab/documents/descriptions.py +++ b/src/lab/documents/descriptions.py @@ -2,21 +2,42 @@ from lab.liquid_classes import HamiltonLiquidClass, LiquidClass from lab.model import ( + LIQUID_STEPS, Distribute, ManualInstruction, Mix, + MultiMix, + MultiTransfer, SetTemperature, Step, Thermocycle, Transfer, Wait, ) +from lab.samples import Location from lab.units import number +def column_of(locations: tuple[Location, ...]) -> str | None: + """``"cultures column 12 (rows A–H)"`` when locations run down one column, else None.""" + if len(locations) < 2 or len({location.resource for location in locations}) != 1: + return None + columns = {location.well[1:] for location in locations} + rows = [location.well[0] for location in locations] + if len(columns) != 1 or rows != sorted(rows) or len(set(rows)) != len(rows): + return None + contiguous = all(ord(b) - ord(a) == 1 for a, b in zip(rows, rows[1:], strict=False)) + span = f"rows {rows[0]}–{rows[-1]}" if contiguous else f"rows {', '.join(rows)}" + return f"{locations[0].resource} column {columns.pop()} ({span})" + + +def _lanes(locations: tuple[Location, ...]) -> str: + return column_of(locations) or ", ".join(str(location) for location in locations) + + def describe(step: Step) -> str: liquid = "" - if isinstance(step, (Transfer, Distribute, Mix)): + if isinstance(step, LIQUID_STEPS): if isinstance(step.liquid_class, LiquidClass): spec = step.liquid_class liquid = ( @@ -32,8 +53,19 @@ def describe(step: Step) -> str: wells = ", ".join(str(destination) for destination in destinations) gap = f" Air gap {number(air_gap)} µL." if air_gap is not None else "" return f"Distribute {number(volume)} µL from {source} to {wells}.{gap}{liquid}" + case MultiTransfer(sources, destinations, volume, _): + lane_count = len(destinations) + origin_text = f"{sources[0]}" if len(set(sources)) == 1 else _lanes(sources) + return ( + f"Transfer {number(volume)} µL along {lane_count} lanes together from " + f"{origin_text} to {_lanes(destinations)}.{liquid}" + ) case Mix(location, volume, cycles, _): return f"Mix {location}: {cycles} cycles of {number(volume)} µL.{liquid}" + case MultiMix(locations, volume, cycles, _): + return ( + f"Mix {_lanes(locations)} together: {cycles} cycles of {number(volume)} µL.{liquid}" + ) case Wait(seconds, _): unit = "second" if seconds == 1 else "seconds" return f"Wait {number(seconds)} {unit}." diff --git a/src/lab/documents/flow.py b/src/lab/documents/flow.py index 3b58832..2d79f2f 100644 --- a/src/lab/documents/flow.py +++ b/src/lab/documents/flow.py @@ -3,7 +3,7 @@ from dataclasses import dataclass from decimal import Decimal -from lab.model import Distribute, Mix, Transfer +from lab.model import Distribute, LiquidStep, Mix, MultiMix, MultiTransfer from lab.units import number @@ -38,7 +38,7 @@ class FlowProfile: def build_flow_profile( index: int, - step: Transfer | Distribute | Mix, + step: LiquidStep, aspiration: Decimal, dispense: Decimal, *, @@ -46,9 +46,14 @@ def build_flow_profile( ) -> FlowProfile: """Calculate nominal V/Q phases; no HTML, ramps, or device delays.""" label = f"Step {index} · {type(step).__name__} · {number(step.volume)} µL" - if isinstance(step, Mix): + if isinstance(step, (Mix, MultiMix)): phases = [(step.volume, aspiration), (step.volume, -dispense)] * step.cycles label += f" × {step.cycles} cycles" + if isinstance(step, MultiMix): + label += f" × {len(step.locations)} wells together" + elif isinstance(step, MultiTransfer): + phases = [(step.volume, aspiration), (step.volume, -dispense)] + label += f" × {len(step.destinations)} lanes together" elif isinstance(step, Distribute): if refill_between_destinations: phases = [(step.volume, aspiration), (step.volume, -dispense)] * len(step.destinations) diff --git a/src/lab/documents/models.py b/src/lab/documents/models.py index a86fcc4..37a80c1 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 @@ -63,6 +64,7 @@ class ProcedureRow: volume_note: str = "" source: Reference | None = None destinations: tuple[Reference, ...] = () + sources: tuple[Reference, ...] = () liquid_class: Reference | None = None air_gap: Decimal | None = None @@ -106,6 +108,8 @@ class PlateMapView: @dataclass(frozen=True) class PreparationFrame: + """The state after one operation. ``sources`` pairs with ``destinations`` when ``lanes``.""" + number: int description: str source: str | None @@ -114,6 +118,8 @@ class PreparationFrame: volumes: tuple[WellVolume, ...] mix_cycles: int = 0 refill_between_destinations: bool = False + sources: tuple[str, ...] = () + lanes: bool = False @dataclass(frozen=True) @@ -122,6 +128,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 +147,4 @@ class Worksheet: procedure: tuple[ProcedureRow, ...] liquid_classes: tuple[LiquidClassView, ...] preparation: PreparationView + advisories: tuple[AdvisoryRow, ...] = () diff --git a/src/lab/documents/preparation.py b/src/lab/documents/preparation.py index bbf9969..41b7a74 100644 --- a/src/lab/documents/preparation.py +++ b/src/lab/documents/preparation.py @@ -12,7 +12,15 @@ ResourceView, WellVolume, ) -from lab.model import Distribute, Mix, SetTemperature, Thermocycle, Transfer +from lab.model import ( + Distribute, + Mix, + MultiMix, + MultiTransfer, + SetTemperature, + Thermocycle, + Transfer, +) from lab.samples import Location from lab.units import number from lab.validation import volume_trace @@ -33,9 +41,11 @@ def build_preparation( for index, volumes in enumerate(trace): source = None destinations: tuple[str, ...] = () + sources: tuple[str, ...] = () active: tuple[str, ...] = () mix_cycles = 0 refill_between_destinations = False + lanes = False description = ( "Before the first operation. Inspect a well to review its inputs and sample details." ) @@ -52,9 +62,19 @@ def build_preparation( f" For each destination, aspirate a fresh {number(step.volume)} µL " "from the source and dispense it completely." ) + elif isinstance(step, MultiTransfer): + sources = tuple(wells[location].reference.anchor for location in step.sources) + source = sources[0] + destinations = tuple( + wells[location].reference.anchor for location in step.destinations + ) + lanes = True elif isinstance(step, Mix): active = (wells[step.location].reference.anchor,) mix_cycles = step.cycles + elif isinstance(step, MultiMix): + active = tuple(wells[location].reference.anchor for location in step.locations) + mix_cycles = step.cycles elif isinstance(step, (Thermocycle, SetTemperature)): active = tuple( well.reference.anchor @@ -70,6 +90,8 @@ def build_preparation( active=active, mix_cycles=mix_cycles, refill_between_destinations=refill_between_destinations, + sources=sources if sources else ((source,) if source else ()), + lanes=lanes, volumes=tuple( WellVolume( well.reference.anchor, diff --git a/src/lab/documents/prepare.py b/src/lab/documents/prepare.py index b6ad969..1933495 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, @@ -20,8 +21,19 @@ ) from lab.documents.preparation import build_preparation from lab.liquid_classes import LiquidClass, LiquidClassSpec -from lab.model import Distribute, Mix, Step, TargetPlan, Transfer +from lab.model import ( + LIQUID_STEPS, + Distribute, + Mix, + MultiMix, + MultiTransfer, + Step, + TargetPlan, + Transfer, + lanes, +) from lab.samples import Location +from lab.tips import tip_count from lab.units import number @@ -32,14 +44,21 @@ def _procedure_row( classes: dict[LiquidClassSpec, Reference], ) -> ProcedureRow: destinations: tuple[Location, ...] - if not isinstance(step, (Transfer, Distribute, Mix)): + sources: tuple[Location, ...] = () + if not isinstance(step, LIQUID_STEPS): return ProcedureRow(index, type(step).__name__, instruction=describe(step)) if isinstance(step, Mix): source, destinations = step.location, () note = f"{step.cycles} cycles" + elif isinstance(step, MultiMix): + source, destinations, sources = step.locations[0], (), step.locations + note = f"{step.cycles} cycles at {len(step.locations)} wells together" elif isinstance(step, Distribute): source, destinations = step.source, step.destinations note = "per destination" + elif isinstance(step, MultiTransfer): + source, destinations, sources = step.sources[0], step.destinations, step.sources + note = f"per lane, {len(destinations)} lanes together" else: source, destinations = step.source, (step.destination,) note = "" @@ -50,6 +69,7 @@ def _procedure_row( volume_note=note, source=locations[source], destinations=tuple(locations[well] for well in destinations), + sources=tuple(locations[well] for well in sources), liquid_class=classes.get(step.liquid_class) if step.liquid_class else None, air_gap=step.air_gap if isinstance(step, Distribute) else None, ) @@ -113,7 +133,7 @@ def _liquid_class( index, step, *rates, refill_between_destinations=target.name == "Manual" ) for index, step in enumerate(steps, 1) - if isinstance(step, (Transfer, Distribute, Mix)) and step.liquid_class == spec + if isinstance(step, LIQUID_STEPS) and step.liquid_class == spec ) if rates is not None else () @@ -131,16 +151,17 @@ def build_worksheet(compilation: compiler.Compilation) -> Worksheet: samples = {sample.id: sample for sample in p.samples} placed = {placement.location: samples[placement.sample_id] for placement in p.placements} used = set(fills) | set(placed) - incoming: dict[Location, list[tuple[int, Transfer | Distribute]]] = {} + incoming: dict[Location, list[tuple[int, Location, Transfer | Distribute | MultiTransfer]]] + incoming = {} for index, step in enumerate(p.steps, 1): - if isinstance(step, (Transfer, Distribute)): - destinations = (step.destination,) if isinstance(step, Transfer) else step.destinations - used.add(step.source) - used.update(destinations) - for destination in destinations: - incoming.setdefault(destination, []).append((index, step)) - elif isinstance(step, Mix): - used.add(step.location) + if isinstance(step, LIQUID_STEPS): + for source, destination in lanes(step): + used.add(source) + if destination is not None and isinstance( + step, (Transfer, Distribute, MultiTransfer) + ): + used.add(destination) + incoming.setdefault(destination, []).append((index, source, step)) locations = { location: Reference(f"location-{index}", str(location)) for index, location in enumerate( @@ -155,7 +176,7 @@ def build_worksheet(compilation: compiler.Compilation) -> Worksheet: dict.fromkeys( step.liquid_class for step in p.steps - if isinstance(step, (Transfer, Distribute, Mix)) and step.liquid_class is not None + if isinstance(step, LIQUID_STEPS) and step.liquid_class is not None ), 1, ) @@ -199,8 +220,8 @@ def build_worksheet(compilation: compiler.Compilation) -> Worksheet: if sample and sample.id in p.output_sample_ids else "Declared sample", incoming=tuple( - IncomingTransfer(i, locations[step.source], step.volume) - for i, step in incoming.get(location, ()) + IncomingTransfer(i, locations[source], step.volume) + for i, source, step in incoming.get(location, ()) ), ) ) @@ -234,7 +255,7 @@ def build_worksheet(compilation: compiler.Compilation) -> Worksheet: protocol=p, target=target, digest=compilation.digest, - tip_count=sum(isinstance(step, (Transfer, Distribute, Mix)) for step in p.steps), + tip_count=tip_count(p), summary=summary, notes=notes, resources=tuple(resources), @@ -245,4 +266,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/sections/procedure.html b/src/lab/documents/templates/sections/procedure.html index aabf7d0..0059cf2 100644 --- a/src/lab/documents/templates/sections/procedure.html +++ b/src/lab/documents/templates/sections/procedure.html @@ -20,7 +20,7 @@

Liquid classes

    {% else %} {{ step.action }} {{ step.volume|number }} µL{% if step.volume_note %}{{ step.volume_note }}{% endif %} - {{ reference(step.source) }} + {% if step.sources %}{% for source in step.sources %}{{ reference(source) }}{% if not loop.last %}
    {% endif %}{% endfor %}{% else %}{{ reference(step.source) }}{% endif %} {% for destination in step.destinations %}{{ reference(destination) }}{% if not loop.last %}
    {% endif %}{% else %}—{% endfor %} {% if step.liquid_class %}{{ reference(step.liquid_class, css_class="liquid-class") }}{% else %}Unspecified{% endif %} diff --git a/src/lab/documents/templates/worksheet.html b/src/lab/documents/templates/worksheet.html index 9f67b5e..ed5f1e7 100644 --- a/src/lab/documents/templates/worksheet.html +++ b/src/lab/documents/templates/worksheet.html @@ -16,9 +16,10 @@

    {{ document.protocol.name }}

    Target
    {{ document.target.name }}
    Operations
    {{ document.procedure|length }}
    -
    Fresh tips
    {{ document.tip_count }}
    +
    Tips
    {{ document.tip_count }}
    Resources
    {{ document.resources|length }}
    Output samples
    {{ document.protocol.output_sample_ids|length }}
    + {% if document.advisories %}{% endif %}