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.
tips()
: how to use tips during the involved instructions.distribute()
: some volume of reagent into the wells of the target labwaretransfer()
: from some wells into equal number of target wellsmix()
: mix by pipetting the content of wellsmix_reagent()
: mix every aliquot by pipettingmake_pre_mix()
: put together the components of a PreMixReagent by pipettingget_tips()
: mount new or used tipsdrop_tips()
: drop or put back tipsset_first_tip()
: position of the given tip type to be used nextcheck_reagents_levels()
: generate instruction to check all defined reagentscheck_reagent_level()
: generate instruction to check reagent volumeshow_check_list()
: to the operatorcomment()
: add a comment to the scriptuser_prompt()
: show a text box to the operator
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.
pick_up_tip()
: pick tips of the given typedrop_tip()
aspirate()
: some volumen from given wellsdispense()
: some volumen to given wells
Protocol-structure or state functions¶
Related to initialization:
def_versions()
set_paths()
init_EvoMode()
set_defaults()
liquid_classes()
carrier_types()
allow_labware()
labware_types()
Related to execution order:
use_version()
initialize()
run()
pre_check()
check_list()
post_check()
done()
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:¶
aspirate_one()
dispense_one()
_dispensemultiwells()
_aspirate_multi_tips()
_multidispense_in_replicas()
comments()
-
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
-
-
class
protocol_steps.
Pipeline
(GUI=None, protocols=None, run_name=None)[source]¶ Bases:
protocol_steps.Executable
Each custom Pipeline need to implement these functions.
-
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_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
-
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’ tipsThe 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.