pudu.sample_preparation

Classes for distributing samples and creating inducer gradients on 96-well plates for characterisation experiments.

  • PlateSamples — distributes a list of samples into replicate wells across a plate.

  • PlateWithGradient — creates a serial inducer-concentration gradient (e.g. IPTG dose-response) across replicate rows on a 96-well plate.

Both subclass SamplePreparation, which provides shared labware loading and well-slot management.

class pudu.sample_preparation.SamplePreparation(test_labware='corning_96_wellplate_360ul_flat', test_position='2', aspiration_rate=0.5, dispense_rate=1.0, tiprack_labware='opentrons_96_filtertiprack_200ul', tiprack_position='9', starting_tip=None, pipette='p300_single_gen2', pipette_position='right', use_temperature_module=False, temperature=4, **kwargs)[source]

Bases: ABC

Abstract base class for all Sample Preparation protocols with shared functionality.

Parameters:

  • test_labware (str)

  • test_position (str)

  • aspiration_rate (float)

  • dispense_rate (float)

  • tiprack_labware (str)

  • tiprack_position (str)

  • starting_tip (str | None)

  • pipette (str)

  • pipette_position (str)

  • use_temperature_module (bool)

  • temperature (int)

__init__(test_labware='corning_96_wellplate_360ul_flat', test_position='2', aspiration_rate=0.5, dispense_rate=1.0, tiprack_labware='opentrons_96_filtertiprack_200ul', tiprack_position='9', starting_tip=None, pipette='p300_single_gen2', pipette_position='right', use_temperature_module=False, temperature=4, **kwargs)[source]

Initialize shared sample preparation hardware parameters.

Parameters:

  • test_labware (str) – Opentrons labware definition string for the destination plate (e.g. a flat-bottom 96-well plate for absorbance readings).

  • test_position (str) – Deck slot string for the destination plate.

  • aspiration_rate (float) – Aspiration speed as a fraction of the pipette’s maximum flow rate (1.0 = full speed).

  • dispense_rate (float) – Dispense speed as a fraction of the pipette’s maximum flow rate.

  • tiprack_labware (str) – Opentrons labware definition string for the tip rack.

  • tiprack_position (str) – Deck slot string for the tip rack.

  • starting_tip (str | None) – Well name of the first tip to use (e.g. 'B1'). When None, starts from 'A1'.

  • pipette (str) – Opentrons pipette model string (e.g. 'p300_single_gen2').

  • pipette_position (str) – Mount side for the pipette ('left' or 'right').

  • use_temperature_module (bool) – If True, load the source rack on a temperature module instead of a plain tube rack.

  • temperature (int) – Target temperature in °C for the temperature module. Only used when use_temperature_module=True.

  • **kwargs – Additional keyword arguments passed to subclasses.

abstractmethod run(protocol)[source]

Abstract method that must be implemented by subclasses.

Parameters:

protocol (ProtocolContext)

class pudu.sample_preparation.PlateSamples(samples, sample_volume=200, sample_stock_volume=1200, replicates=4, starting_slot=1, temp_module_position='1', temp_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', tube_rack_position='3', tube_rack_labware='opentrons_24_tuberack_nest_1.5ml_snapcap', **kwargs)[source]

Bases: SamplePreparation

Distribute multiple samples across a 96-well plate with column-grouped replicates.

Each sample is dispensed into replicates consecutive wells within the same column group. Samples are loaded sequentially from a source tube rack (or temperature module), and the plate layout is recorded in result_dict for downstream analysis.

Parameters:

  • samples (List[str])

  • sample_volume (float)

  • sample_stock_volume (float)

  • replicates (int)

  • starting_slot (int)

  • temp_module_position (str)

  • temp_module_labware (str)

  • tube_rack_position (str)

  • tube_rack_labware (str)

__init__(samples, sample_volume=200, sample_stock_volume=1200, replicates=4, starting_slot=1, temp_module_position='1', temp_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', tube_rack_position='3', tube_rack_labware='opentrons_24_tuberack_nest_1.5ml_snapcap', **kwargs)[source]

Initialize PlateSamples protocol.

Parameters:

  • samples (List[str]) – Ordered list of sample names. Each name maps to one source tube and one well group on the destination plate.

  • sample_volume (float) – Volume to dispense into each replicate well, in µL.

  • sample_stock_volume (float) – Volume of each sample stock tube, in µL. Used for liquid tracking on the Opentrons deck visualiser.

  • replicates (int) – Number of replicate wells per sample on the destination plate.

  • starting_slot (int) – 1-based index of the first column slot to use on the destination plate. Allows pre-filling some slots before this protocol runs.

  • temp_module_position (str) – Deck slot string for the temperature module (used when use_temperature_module=True).

  • temp_module_labware (str) – Opentrons labware definition string for the aluminum block on the temperature module.

  • tube_rack_position (str) – Deck slot string for the source tube rack.

  • tube_rack_labware (str) – Opentrons labware definition string for the source tube rack.

  • **kwargs – Passed to SamplePreparation.__init__.

run(protocol)[source]

Execute the sample distribution protocol on the OT-2.

Loads source tubes, validates plate capacity, then distributes each sample into replicates wells using the pipette distribute command (single tip per sample). Results are stored in result_dict with keys 'source_positions' and 'plate_layout'.

Parameters:

protocol (ProtocolContext) – Opentrons ProtocolContext provided by the OT-2 runtime.

Raises:

ValueError – If the number of samples exceeds source rack or plate slot capacity.

class pudu.sample_preparation.PlateWithGradient(sample_name, inducer_name, initial_concentration=1.0, dilution_factor=2.0, dilution_steps=8, replicates=3, starting_row='A', final_well_volume=200, initial_mix_ratio=0.5, transfer_volume=100, sample_stock_volume=1200, inducer_stock_volume=1200, temp_module_position='1', temp_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', tube_rack_position='3', tube_rack_labware='opentrons_24_tuberack_nest_1.5ml_snapcap', **kwargs)[source]

Bases: SamplePreparation

Create a serial inducer-concentration gradient across a 96-well plate.

The first well in each replicate row receives a stock mixture of sample and inducer at initial_concentration. Each subsequent well is diluted by dilution_factor through sequential well-to-well transfers, producing a dilution_steps-point gradient. The sample serves as the diluent.

Typical use case: dose-response characterisation of a genetic circuit where the sample is a cell culture and the inducer is a small molecule (e.g. IPTG, arabinose).

Parameters:

  • sample_name (str)

  • inducer_name (str)

  • initial_concentration (float)

  • dilution_factor (float)

  • dilution_steps (int)

  • replicates (int)

  • starting_row (str)

  • final_well_volume (float)

  • initial_mix_ratio (float)

  • transfer_volume (float)

  • sample_stock_volume (float)

  • inducer_stock_volume (float)

  • temp_module_position (str)

  • temp_module_labware (str)

  • tube_rack_position (str)

  • tube_rack_labware (str)

__init__(sample_name, inducer_name, initial_concentration=1.0, dilution_factor=2.0, dilution_steps=8, replicates=3, starting_row='A', final_well_volume=200, initial_mix_ratio=0.5, transfer_volume=100, sample_stock_volume=1200, inducer_stock_volume=1200, temp_module_position='1', temp_module_labware='opentrons_24_aluminumblock_nest_1.5ml_snapcap', tube_rack_position='3', tube_rack_labware='opentrons_24_tuberack_nest_1.5ml_snapcap', **kwargs)[source]

Initialize PlateWithGradient protocol.

Parameters:

  • sample_name (str) – Human-readable name for the sample (e.g. 'DH5alpha_GFP'). Used for liquid tracking labels.

  • inducer_name (str) – Human-readable name for the inducer (e.g. 'IPTG').

  • initial_concentration (float) – Inducer concentration in the first well, in whatever units the user chooses (e.g. mM, ng/µL). Used only for labelling concentration_map; does not affect volumes.

  • dilution_factor (float) – Factor by which concentration decreases at each step (e.g. 2.0 for 2-fold dilutions).

  • dilution_steps (int) – Number of dilution transfers after the initial well, giving dilution_steps + 1 total wells per replicate row.

  • replicates (int) – Number of replicate rows on the plate.

  • starting_row (str) – Letter of the first plate row to use (e.g. 'A').

  • final_well_volume (float) – Target total volume in each well after all additions, in µL. The diluent (sample) pre-fill volume is final_well_volume − transfer_volume.

  • initial_mix_ratio (float) – Fraction of final_well_volume that is inducer in the first well (e.g. 0.5 → equal parts inducer and sample).

  • transfer_volume (float) – Volume moved from each well to the next during the serial dilution, in µL.

  • sample_stock_volume (float) – Total volume of the sample stock tube, in µL. Used for liquid tracking.

  • inducer_stock_volume (float) – Total volume of the inducer stock tube, in µL. Used for liquid tracking.

  • temp_module_position (str) – Deck slot string for the temperature module.

  • temp_module_labware (str) – Opentrons labware definition string for the aluminum block on the temperature module.

  • tube_rack_position (str) – Deck slot string for the source tube rack.

  • tube_rack_labware (str) – Opentrons labware definition string for the source tube rack.

  • **kwargs – Passed to SamplePreparation.__init__.

run(protocol)[source]

Abstract method that must be implemented by subclasses.

Parameters:

protocol (ProtocolContext)