Principal API: Protocol steps

All these functions are member of the base class Protocol, from which all user protocols are derived.

High level functions:

These are the functions you will use in “every day” protocol programming. They allow you to specify the kind of tips to use and them command the operations you need on your reagents, samples, reactions, etc., almost directly as it states in the steps of your “hand written” original laboratory protocol.

Advanced functions.

Are you doing some advanced protocol development that cannot be efficiently or clearly expressed using the previous High level functions? Then, you may use the following functions.

Atomic functions

These are functions aimed to isolate what a physical robot would make at once: pick some tips, aspirate some liquid, etc. They are simple to understand, but are harder to use in “every day” protocol programming. They may be a great tool to set up your robot and to get an initial familiarization with all the system. Keep in mind that it is now your responsibility to know what robot/protocol “state” are ignored by these new functions. For example, before aspirate you will need to mount “by yourself” the tips in the correct position of the used arm, because aspirate ignores the higher level with tips(). But don’t worry, RobotEvo still keeps track of the “internal” robot state and will throw errors informing you about most logical mistakes (like in the previous example forgetting to mount the tips). In some cases these functions may be used to construct new high lever functions.

Protocol-structure or state functions

Related to initialization:

Related to execution order:

Related to state:

  • get_liquid_class()
  • get_carrier_type()
  • get_labware_type()
  • set_EvoMode()
  • set_drop_tips()
  • set_allow_air()
  • reuse_tips()
  • reuse_tips_and_drop()
  • preserve_tips()
  • preserveing_tips()
  • use_preserved_tips()

Other intermediate level functions:


class protocol_steps.Executable(GUI=None, run_name=None)[source]

Bases: object

Each executable will need to implement these methods.

__init__(GUI=None, run_name=None)[source]

Initialize self. See help(type(self)) for accurate signature.

def_versions()[source]

Override this function to define a ‘dictionary’ of the versions for your Executable, with a name as key and a method as value, which will initialize the Executable to effectively execute that version. You don’t need to call this function. It will be used internally during initialization of your derived class.

initialize()[source]

It is called “just in case” to ensure we don’t go uninitialized in lazy initializing scenarios.

run()[source]

Here we have accesses to the “internal robot” self.iRobot, with in turn have access to the used Work Table, self.iRobot.worktable from where we can obtain labwares with get_labware(). Overwrite this function and dont call this basic function. This basic function is provided only as an example of “boiled-plate” code

set_defaults()[source]

Set initial values that will not be rest during secondary initializations. The “primary initialization” maybe a light one, like defining the list of versions available. Here, for example, initialize the list of reagents. # todo: make private

use_version(version: str)[source]

Select the version to be execute

Parameters:version (str) – the name of the desired version
class protocol_steps.Pipeline(GUI=None, protocols=None, run_name=None)[source]

Bases: protocol_steps.Executable

Each custom Pipeline need to implement these functions.

__init__(GUI=None, protocols=None, run_name=None)[source]

Initialize self. See help(type(self)) for accurate signature.

class protocol_steps.Protocol(n_tips=4, num_of_samples=96, GUI=None, worktable_template_filename=None, output_filename=None, first_tip=None, run_name=None, tips_type=None)[source]

Bases: protocol_steps.Executable

Base class from which each custom protocol need to be derived, directly or from one of already derived. For example from the already adapted to some generic type robot like Evo200 or from an even more especially adapted like Evo100_FLI. Each newly derived protocol have to optionally override some of the following functions, especially .run().

  • High level API:
  • App-Structure API:
  • Context-options modifiers:
  • Lower lever API & “private” functions:
  • Atomic API:
__init__(n_tips=4, num_of_samples=96, GUI=None, worktable_template_filename=None, output_filename=None, first_tip=None, run_name=None, tips_type=None)[source]
Parameters:
  • n_tips
  • num_of_samples
  • GUI
  • worktable_template_filename
  • output_filename
  • first_tip
  • run_name
  • tips_type
aspirate(arm: EvoScriPy.robot.Arm = None, TIP_MASK: int = None, volume: (<class 'float'>, <class 'list'>) = None, from_wells: [<class 'EvoScriPy.labware.Well'>] = None, liq_class: str = None)[source]

Atomic operation. Use arm (pipette) with masked (selected) tips to aspirate volume from wells. :param arm: Uses the default Arm (pipette) if None :param TIP_MASK: Binary flag bit-coded (tip1=1, tip8=128) selects tips to use in a multichannel pipette arm.

If None all tips are used. (see Robot.mask_tip[index] and Robot.mask_tips[index])
Parameters:
  • volume – One (the same) for each tip or a list specifying the volume for each tip.
  • from_wells – list of wells to aspirate from.
  • liq_class – the name of the Liquid class, as it appears in your own EVOware database. instructions.def_liquidClass if None
aspirate_one(tip, reagent, vol=None, offset=None)[source]

Aspirate vol with ONE tip from reagent

Parameters:
  • self
  • tip
  • reagent
  • vol
  • offset
check_list()[source]

Tipically

check_reagent_level(reagent, liq_class=None)[source]

Select all possible replica of the given reagent and detect the liquid level, contrasting it with the current (expected) volumen in EACH well. Use the given liquid class or the reagent default.

Parameters:
  • reagent
  • liq_class
check_reagents_levels()[source]

Will emit a liquid level detection on every well occupied by all the reagents defined so fort. Will be executed at the end of self.check_list() but only if self.check_initial_liquid_level is True

comment(text: str)[source]

Add a text comment in the generated script :param text:

consolidate()[source]

Volumes going to the same destination well are combined within the same tip, so that multiple aspirates can be combined to a single dispense. If there are multiple destination wells, the pipette will never combine their volumes into the same tip. :return:

dispense(arm: EvoScriPy.robot.Arm = None, TIP_MASK: int = None, volume: (<class 'float'>, <class 'list'>) = None, to_wells: [<class 'EvoScriPy.labware.Well'>] = None, liq_class: str = None)[source]

Atomic operation. Use arm (pipette) with masked (selected) tips to dispense volume to wells.

Parameters:
  • arm – Uses the default Arm (pipette) if None
  • TIP_MASK – Binary flag bit-coded (tip1=1, tip8=128) selects tips to use in a multichannel pipette arm. If None all tips are used. (see Robot.mask_tip[index] and Robot.mask_tips[index])
  • volume – One (the same) for each tip or a list specifying the volume for each tip.
  • to_wells – list of wells to aspirate from.
  • liq_class – the name of the Liquid class, as it appears in your own EVOware database. instructions.def_liquidClass if None
dispense_one(tip, reagent, vol=None)[source]

Dispense vol with ONE tip to reagent

Parameters:
  • tip
  • reagent
  • vol
distribute(volume: float = None, reagent: EvoScriPy.reagent.Reagent = None, to_labware_region: EvoScriPy.labware.Labware = None, optimize: bool = True, num_samples: int = None, using_liquid_class: (<class 'str'>, <class 'tuple'>) = None, TIP_MASK: int = None, num_tips: int = None)[source]
Parameters:
  • volume – if not, volume is set from the default of the source reagent
  • reagent – Reagent to distribute
  • to_labware_region – Labware in which the destine well are selected
  • optimize – minimize zigzag of multi pipetting
  • num_samples – Priorized !!!! If true reset the selection
  • using_liquid_class
  • TIP_MASK
  • num_tips – the number of tips to be used in each cycle of pipetting = all

To distribute a reagent into some wells. This is a high level function with works with the concept of “reagent”. This a a concept introduced by RobotEvo that don’t exist in EVOware and other similar software. It encapsulated the name, wells occupied by each of the aliquots of the reagent, the volume corresponding to one sample (if any) and the current volume in each aliquot. This function can use multiple of those aliquots to distribute the reagent to the target wells using multiple tips (the maximum will be used if num_tips is not set).

By default a number of wells equal to the number of samples set in the protocol will be auto selected in the target labware to_labware_region, but this selection can be set explicitly (setting well.selFlag=True, for example by calling to_labware_region.selectOnly(self, sel_idx_list)). If num_samples is set it will rewrite (reset) the selected wells in the target to_labware_region.

Please, carefully indicate whether to use “parallel optimization” in the pipetting order by setting optimize. (very important unless you are using a full column pipetting arm). Check that the created script don’t have conflicts in the order of the samples and the “geometry” of the labware areas (selection of wells) during each pipetting step. This is ease to “see” in the EVOware visual script editor. The generated .protocol.txt can also be used to check this. RobotEvo will detect some errors, but currently not all, assuming the areas are relatively “regular”.

The same volume will be transfer to each well. It will be dispensed in only one pass: muss fit into the current tips If the liquid classes (LC) to be used are not explicitly passed the default LC of the reagent will be used. The generated .esc and .gwl can also be used to check this.

A human readable comment will be automatically added to the script with the details of this operation.

drop_tip(TIP_MASK: int = None, DITI_waste: EvoScriPy.labware.Labware = None, arm: EvoScriPy.robot.Arm = None, airgap_volume: float = 0, airgap_speed: int = None)[source]
Parameters:
  • TIP_MASK – Binary flag bit-coded (tip1=1, tip8=128) selects tips to use in a multichannel pipette arm. If None all tips are used. (see Robot.mask_tip[index] and Robot.mask_tips[index])
  • DITI_waste – Specify the worktable position for the DITI waste you want to use. You must first put a DITI waste in the Worktable at the required position.
  • arm – Uses the default Arm (pipette) if None
  • airgap_speed – int 1-1000. Speed for the airgap in μl/s
  • airgap_volume – 0 - 100. Airgap in μl which is aspirated after dropping the DITIs
drop_tips(TIP_MASK=None)[source]

It will decide to really drop the tips or to put it back in some DiTi rack

Parameters:TIP_MASK
get_tips(TIP_MASK=None, tip_type=None, selected_samples=None)[source]

It will decide to get new tips or to pick back the preserved tips for the selected samples

Parameters:
  • TIP_MASK
  • tip_type
  • selected_samples
Returns:

the TIP_MASK used

initialize()[source]

It is called “just in case” to ensure we don’t go uninitialized in lazy initializing scenarios.

make_pre_mix(pre_mix: EvoScriPy.reagent.PreMixReagent, num_samples: int = None, force_replies: bool = False)[source]

A preMix is just that: a premix of reagents (aka - components) which have been already defined to add some vol per sample. Uses one new tip per component. It calculates and checks self the minimum and maximum number of replica of the resulting preMix

Parameters:
  • pre_mix (PreMixReagent) – what to make, a predefined preMix
  • num_samples (int) –
  • force_replies (bool) – use all the preMix predefined replicas
mix(in_labware_region: EvoScriPy.labware.Labware, using_liquid_class: str = None, volume: float = None, optimize: bool = True)[source]

MixReagent the reagents in each of the wells selected in_labware_region, using_liquid_class and volume

Parameters:
  • in_labware_region
  • using_liquid_class
  • volume
  • optimize
mix_reagent(reagent: EvoScriPy.reagent.Reagent, liq_class: str = None, cycles: int = 3, maxTips: int = 1, v_perc: int = 90)[source]

Select all possible replica of the given reagent and mix using the given % of the current vol in EACH well or the max vol for the tip. Use the given “liquid class” or the reagent default.

Parameters:
  • reagent
  • liq_class
  • cycles
  • maxTips
  • v_perc – % of the current vol in EACH well to mix
pick_up_tip(TIP_MASK: int = None, tip_type: (<class 'str'>, <class 'EvoScriPy.labware.DITIrackType'>, <class 'EvoScriPy.labware.DITIrack'>, <class 'EvoScriPy.labware.DITIrackTypeSeries'>) = None, arm: EvoScriPy.robot.Arm = None, airgap_volume: float = 0, airgap_speed: int = None)[source]

Atomic operation. Get new tips. It take a labware type or name instead of the labware itself (DiTi rack) because the real robot take track of the next position to pick, including the rack and the site (the labware). It only need a labware type (tip type) and it know where to pick the next tip. Example:

self.pick_up_tip(‘DiTi 200 ul’) # will pick a 200 ul tip with every tip arm.
Parameters:
  • TIP_MASK – Binary flag bit-coded (tip1=1, tip8=128) selects tips to use in a multichannel pipette arm. If None all tips are used. (see Robot.mask_tip[index] and Robot.mask_tips[index])
  • tip_type – if None the worktable default DiTi will be used.
  • arm – Uses the default Arm (pipette) if None
  • airgap_speed – int 1-1000. Speed for the airgap in μl/s
  • airgap_volume – 0 - 100. Airgap in μl which is aspirated after dropping the DITIs
reuse_tips(reuse=True) → bool[source]

Reuse the tips or drop it and take new after each action?

Parameters:reuse (bool) –
Returns:
run()[source]

Here we have accesses to the “internal robot” self.iRobot, with in turn have access to the used Work Table, self.iRobot.worktable from where we can obtain labwares with get_labware()

set_defaults()[source]

Set initial values that will not be rest during secondary initializations. The “primary initialization” maybe a light one, like defining the list of versions available. Here, for example, initialize the list of reagents. # todo: make private

set_drop_tips(drop=True) → bool[source]

Drops the tips at THE END of the whole action? like after distribution of a reagent into various targets :param drop: :return:

set_first_tip(first_tip: (<class 'int'>, <class 'str'>) = None, tip_type: (<class 'str'>, <class 'EvoScriPy.labware.DITIrackType'>) = None)[source]

Optionally set the Protocol.first_tip, a position in rack, like 42 or ‘B06’ (optionally including the rack self referenced with a number, like ‘2-B06’, were 2 will be the second rack in the worktable series of the default tip type). Currently, for a more precise set, use directly:

instructions.set_DITI_Counter2(labware=rack, posInRack=first_tip).exec()
show_check_list()[source]

Will show a user prompt with a check list to set all defined reagents: Name, position in the worktable, wells and initial volume (on every well occupied by all the reagents defined so fort. Will be executed at the end of self.check_list() but only if self.show_runtime_check_list is True

tips(tips_mask=None, tip_type=None, reuse=None, drop=None, preserve=None, use_preserved=None, drop_first=False, drop_last=False, allow_air=None, selected_samples: EvoScriPy.labware.Labware = None)[source]

A contextmanager function which will manage how tips will be used during execution of the dependant instructions

Parameters:
  • tips_mask
  • tip_type – the type of the tips to be used
  • reuse (bool) – Reuse the tips already mounted? or drop and take new BEFORE each individual action
  • drop (bool) – Drops the tips AFTER each individual action? like after one aspiration and distribute of the reagent into various targets
  • preserve (bool) – puts the tip back into a free place in some rack of the same type
  • use_preserved – pick the tips back from the previously preserved
  • selected_samples
  • allow_air
  • drop_first (bool) – Reuse the tips or drop it and take new once BEFORE the whole action
  • drop_last (bool) – Drops the tips at THE END of the whole action
transfer(from_labware_region: EvoScriPy.labware.Labware, to_labware_region: EvoScriPy.labware.Labware, volume: (<class 'int'>, <class 'float'>), using_liquid_class: (<class 'str'>, <class 'tuple'>) = None, optimize_from: bool = True, optimize_to: bool = True, num_samples: int = None) -> (<class 'EvoScriPy.labware.Labware'>, <class 'EvoScriPy.labware.Labware'>)[source]
Parameters:
  • from_labware_region (Labware) – Labware in which the source wells are located and possibly selected
  • to_labware_region (Labware) – Labware in which the target wells are located and possibly selected
  • volume (float) – if not, volume is set from the default of the source reagent
  • using_liquid_class – LC or tuple (LC to aspirate, LC to dispense)
  • optimize_from (bool) – use from_labware_region.parallelOrder() to aspirate?
  • optimize_to (bool) – use to_labware_region.parallelOrder() to aspirate?
  • num_samples (int) – Prioritized. If used reset the well selection
Returns:

a tuple of the labwares used as origin and target with the involved wells selected.

To transfer reagents (typically samples or intermediary reactions) from some wells in the source labware to the same number of wells in the target labware using the current LiHa arm with maximum number of tips (of type: self.worktable.def_DiTi_type, which can be set ‘with self. tips() (tip_type = myTipsRackType)’). # todo: count for ‘broken’ tips

The number of “samples” may be explicitly indicated in which case will be assumed to begin from the first well of the labware. Alternatively the wells in the source or target or in both may be previously directly “selected” (setting well.selFlag=True, for example by calling from_labware_region.selectOnly(self, sel_idx_list)), in which case transfer the minimum length selected. If no source wells are selected this function will auto select the protocol’s self.num_of_samples number of wells in the source and target labwares. Please, carefully indicate whether to use “parallel optimization” in the pipetting order for both source and target by setting optimizeFrom and optimizeTo. (very important unless you are using a full column pipetting arm). Check that the created script don’t have conflicts in the order of the samples and the “geometry” of the labware areas (selection of wells) during each pipetting step. This is ease to “see” in the EVOware visual script editor. The generated .protocol.txt can also be used to check this. RobotEvo will detect some errors, but currently not all, assuming the areas are relatively “regular”.

The same volume will be transfer from each well. It will be aspirated/dispensed in only one pass: muss fit into the current tips todo ?! If no volume is indicated then the volume expected to be in the first selected well will be used.

If the liquid classes (LC) to be used are not explicitly passed the default LC in the first well of the current pipetting step will be used. The generated .esc and .gwl can also be used to check this.

A human readable comment will be automatically added to the script with the details of this operation.

Warning: modify the selection of wells in both source and target labware to reflect the wells actually used

user_prompt(text: str, sound: bool = True, close_time: int = -1)[source]

Interrupt pippeting to popup a message box to the operator.

Parameters:
  • text – the text in the box
  • sound – Should add an acustic signal?
  • close_time – time to wait for automatic closing the box: the operator can “manually”
close this box at any time, and this will be the only way to close it if the default -1 is used,
which cause no automatic closing.