Reagent - a fundamental concept

A Reagent is a fundamental concept in RobotEvo programming. It makes possible to define a protocol in a natural way, matching what a normal laboratory’s protocol indicates. Defines a named homogeneous liquid solution, the wells it occupy, the initial amount needed to run the protocol (auto calculated), and how much is needed per sample, if applicable. It is also used to define samples, intermediate reactions and products. It makes possible a robust tracking of all actions and a logical error detection, while significantly simplifying the programming of non trivial protocols.

todo: implement units for volume, concentration, etc.

Main classes and functions:

Abstract information classes:

  • MixComponent: like an item in some table summarizing components of some Mix.
  • PreMixComponent: like an item in some table summarizing components of some PreMix.
  • Primer: like an item in some table summarizing primer sequences, synthesis, etc.
  • PrimerMixComponent: like an item in a table describing Primer Mixes for some PCRs.
  • PrimerMix: like a table describing Primer Mixes for some PCRs
  • PCRMasterMix: like an item in some table summarizing PCR Master Mixes for some PCR experiment
  • PCReaction: like an item in some table summarizing reactions in a PCR experiment
  • PCRexperiment: like an item in some table summarizing PCR experiments

Robot classes:

class reagent.Dilution(name: str, diluent: reagent.Reagent, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, components: [<class 'reagent.DilutionComponentReagent'>] = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, excess: float = None, initial_vol: float = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]

Bases: reagent.MixReagent

A Reagent composed of others, diluted Reagents, that the robot may prepare.

__init__(name: str, diluent: reagent.Reagent, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, components: [<class 'reagent.DilutionComponentReagent'>] = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, excess: float = None, initial_vol: float = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]
Parameters:
  • name
  • labware
  • wells
  • components
  • num_of_aliquots
  • minimize_aliquots
  • def_liq_class
  • excess
  • initial_vol
  • min_vol
  • fill_limit_aliq
  • concentration
components = None

list of reagent components

class reagent.DilutionComponentReagent(reagent: reagent.Reagent, dilution: float = None, final_conc: float = None)[source]

Bases: reagent.MixComponentReagent

Components of some Dilution.

__init__(reagent: reagent.Reagent, dilution: float = None, final_conc: float = None)[source]
Parameters:
  • reagent
  • dilution
  • final_conc
class reagent.MixComponent(name: str, id_: str = None, init_conc: float = None, final_conc: float = None, volume: float = None)[source]

Bases: object

Represent abstract information, like an item in some table summarizing components of some MixReagent. todo: introduce diluent? - final_conc == None ? final_conc == init_conc ?

__init__(name: str, id_: str = None, init_conc: float = None, final_conc: float = None, volume: float = None)[source]
Parameters:
  • id
  • name
  • init_conc – todo Really??
  • final_conc
class reagent.MixComponentReagent(reagent: reagent.Reagent, volume: float = None)[source]

Bases: object

Components of some MixReagent. This is not just a Reagent, but some “reserved” volume of some Reagent.

__init__(reagent: reagent.Reagent, volume: float = None)[source]
Parameters:
  • reagent
  • volume
class reagent.MixReagent(name: str, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, components: [<class 'reagent.MixComponentReagent'>] = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, excess: float = 1.0, initial_vol: float = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]

Bases: reagent.Reagent

A Reagent composed of other Reagents, that the robot may prepare.

__init__(name: str, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, components: [<class 'reagent.MixComponentReagent'>] = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, excess: float = 1.0, initial_vol: float = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]
Parameters:
  • name
  • labware
  • wells
  • components
  • num_of_aliquots
  • minimize_aliquots
  • def_liq_class
  • excess
  • initial_vol
  • min_vol
  • fill_limit_aliq
  • concentration
components = None

list of reagent components

exception reagent.NoReagentFound(reagent_name: str, error: str)[source]

Bases: Exception

__init__(reagent_name: str, error: str)[source]

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

class reagent.PCRMasterMix(name, id_=None, reaction_vol=25, sample_vol=5, components=None, diluent=None, title=None)[source]

Bases: object

Represent abstract information, like an item in some table summarizing PCR Master Mixes for some PCR experiment

__init__(name, id_=None, reaction_vol=25, sample_vol=5, components=None, diluent=None, title=None)[source]
Parameters:
  • name
  • id
  • reaction_vol
  • sample_vol
  • components
  • title
ids = {}

connect each existing PCR master mix ID with the corresponding PCRMasterMix

names = {}

connect each existing PCR master mix name with the corresponding PCRMasterMix

class reagent.PCRMasterMixReagent(pcr_mix: reagent.PCRMasterMix, mmix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), num_of_samples: int, pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, kit_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None)[source]

Bases: reagent.PreMixReagent

Manipulate a PCR Master-Mix Reagent on a robot.

__init__(pcr_mix: reagent.PCRMasterMix, mmix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), num_of_samples: int, pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, kit_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None)[source]

Construct a robot-usable PCRMasterMixReagent from an abstract PCRMasterMix. It is always constructed - no reuse of old aliquots: contains instable components.

Parameters:
  • primer_mix_rack
  • primer_rack
  • pos
  • num_of_aliquots
  • initial_vol
  • def_liq_class
  • fill_limit_aliq
  • pcr_mix
  • mmix_rack
  • kit_rack
  • excess
class reagent.PCReaction(rol, sample=None, targets=None, mix: reagent.PCRMasterMix = None, replica=None, row=None, col=None, vol=None)[source]

Bases: object

Represent abstract information, like an item in some table summarizing reactions in a PCR experiment

__init__(rol, sample=None, targets=None, mix: reagent.PCRMasterMix = None, replica=None, row=None, col=None, vol=None)[source]

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

class reagent.PCReactionReagent(pcr_reaction: reagent.PCReaction, plate: EvoScriPy.labware.Labware)[source]

Bases: reagent.Reaction

__init__(pcr_reaction: reagent.PCReaction, plate: EvoScriPy.labware.Labware)[source]
Parameters:
  • pcr_reaction
  • plates
class reagent.PCRexperiment(id_=None, name=None, ncol=0, nrow=0)[source]

Bases: object

Represent abstract information, like an item in some table summarizing PCR experiments

__init__(id_=None, name=None, ncol=0, nrow=0)[source]

A linear rack have just one roe and many columns

Parameters:
  • id
  • name
  • ncol
  • nrow
mixes = {}

connect each PCR master mix with a list of well reactions

pcr_reactions = None

list of PCRReaction to create organized in rows with columns

samples = None

connect each sample with a list of well reactions

targets = None

connect each target with a list of PCR reactions well

class reagent.PCRexperimentRtic(pcr_exp: (<class 'reagent.PCRexperiment'>, <class 'list'>), plates: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), kit_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), mmix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, protocol=None)[source]

Bases: object

Organize a PCR setup on a robot. From a list of abstract information about PCR plate/experiments creates sufficient volume of each of the PCRMasterMixReagent listed in the global PCRexperiment.mixes

__init__(pcr_exp: (<class 'reagent.PCRexperiment'>, <class 'list'>), plates: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), kit_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), mmix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None, protocol=None)[source]
Parameters:
  • pcr_exp – [PCRexperiment] abstarct information about the “plate” PCR experiemnts
  • plates – [labware.Labware] where to set the PCR reactions.
  • kit_rack – [racks] in the prefered order to put the PCR kit reagents (stocks solutions)
  • mmix_rack – [racks] in the prefered order to put the PCR mastermix reagents specially created for these experiments
  • primer_mix_rack – [racks] in the prefered order to put the primer mix reagents (stocks solutions)s
  • primer_rack – [racks] in the prefered order to put the primers reagents (stocks solutions)s
  • protocol – who invoke this PCR, provide a worktable and the rest of the “environment”
mixes = None

connect each PCRMasterMix in the experiment with the PCR wells into which will be pippeted

pcr_exp = None

abstract info

class reagent.PreMixComponent(name: str, volpersample: float, id_: str = None, init_conc: float = None, final_conc: float = None, volume: float = None)[source]

Bases: reagent.MixComponent

Represent abstract information, like an item in some table summarizing components of some PreMixReagent. An special case of MixComponent, for which volume is calculated on the basis of “number of samples” and volume_per_sample

__init__(name: str, volpersample: float, id_: str = None, init_conc: float = None, final_conc: float = None, volume: float = None)[source]
Parameters:
  • id
  • name
  • init_conc – todo Really??
  • final_conc
class reagent.PreMixReagent(name, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), components, pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, num_of_samples=None)[source]

Bases: reagent.Reagent

A pre-MixReagent of otherwise independent reagents to be pippeted together for convenience, but that could be pippeted separately. todo: make this a special case of MixReagent, for which everything ? is calculated on the basis of “number of samples”

__init__(name, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), components, pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, num_of_samples=None)[source]
Parameters:
  • name
  • labware
  • components – list of reagent components
  • pos
  • num_of_aliquots
  • initial_vol
  • def_liq_class
  • excess
  • fill_limit_aliq
  • num_of_samples
components = None

list of reagent components

init_vol(num_samples=None, initial_vol=None)[source]

update my self.volpersample from the already updated self.components.volpersample, possibly with updated num_samples and initial_vol WARNING !! call this only after the update of the components (if need) :param num_samples: :param initial_vol:

class reagent.Primer(name: str, seq: str, proposed_stock_conc: float = 100, id_: str = None, prepared: float = None, mass: float = None, moles: float = None, molec_w: float = None, mod_5p: str = None, mod_3p: str = None, id_synt: str = None, kws: list = None, diluent: str = 'TE 1x')[source]

Bases: object

Represent abstract information, like an item in some table summarizing primer sequences, synthesis, etc.

__init__(name: str, seq: str, proposed_stock_conc: float = 100, id_: str = None, prepared: float = None, mass: float = None, moles: float = None, molec_w: float = None, mod_5p: str = None, mod_3p: str = None, id_synt: str = None, kws: list = None, diluent: str = 'TE 1x')[source]
Parameters:
  • name
  • seq
  • proposed_stock_conc
  • id
  • prepared
  • mass
  • moles
  • molec_w
  • mod_5p
  • mod_3p
  • id_synt
  • kws
  • diluent
ids = {}

connect each existing Primer ID with the corresponding Primer

ids_synt = {}

connect each existing Primer synthesis ID with the corresponding Primer

key_words = {}

connect each existing Primer key_word with the corresponding list of Primer

names = {}

connect each existing Primer name with the corresponding list of Primer

seqs = {}

connect each existing Primer sequence with the corresponding list of Primer

class reagent.PrimerMix(name, id_=None, conc=10.0, prepared=None, components=None, ref_vol=None, diluent=None, kws=None, super_mix=False)[source]

Bases: object

Represent abstract information, like a table describing Primer Mixes for some PCRs

__init__(name, id_=None, conc=10.0, prepared=None, components=None, ref_vol=None, diluent=None, kws=None, super_mix=False)[source]
Parameters:
  • name
  • id
  • conc
  • prepared
  • components
  • ref_vol
  • diluent
  • kws
  • super_mix
ids = {}

connect each existing Primer mix ID with the corresponding PrimerMix

key_words = {}

connect each existing Primer mix key_word with the corresponding list of PrimerMix

names = {}

connect each existing Primer mix name with the corresponding list of PrimerMix

class reagent.PrimerMixComponent(id_=None, name=None, init_conc=None, final_conc=None, super_mix: bool = False)[source]

Bases: reagent.MixComponent

Represent abstract information, like an item in a table describing Primer Mixes for some PCRs. It can be a primer, another primer mix or the diluent

__init__(id_=None, name=None, init_conc=None, final_conc=None, super_mix: bool = False)[source]
Parameters:
  • id
  • name
  • init_conc
  • final_conc
  • super_mix
class reagent.PrimerMixReagent(primer_mix: reagent.PrimerMix, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None)[source]

Bases: reagent.PreMixReagent

Manipulate a Primer-MixReagent Reagent on a robot.

__init__(primer_mix: reagent.PrimerMix, primer_mix_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), pos=None, num_of_aliquots=None, initial_vol=None, def_liq_class=None, excess=None, fill_limit_aliq=None, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>) = None)[source]

Construct a robot-usable PrimerMixReagent from an abstract PrimerMix. You can reuse “old” aliquots by passing primer_mix.prepared volume > 0. If no primer_mix.prepared volume is passed, or if it is not sufficient, a set of primer reagents will be created.

Parameters:
  • primer_mix
  • primer_mix_rack
  • pos
  • num_of_aliquots
  • initial_vol
  • def_liq_class
  • excess
  • fill_limit_aliq
  • primer_rack
class reagent.PrimerReagent(primer: reagent.Primer, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), pos=None, initial_vol=None, PCR_conc=0.8, stk_conc=100, def_liq_class=None, fill_limit_aliq=None, excess=None)[source]

Bases: reagent.MixReagent

Manipulate a Primer Reagent on a robot.

__init__(primer: reagent.Primer, primer_rack: (<class 'EvoScriPy.labware.Labware'>, <class 'list'>), pos=None, initial_vol=None, PCR_conc=0.8, stk_conc=100, def_liq_class=None, fill_limit_aliq=None, excess=None)[source]

Construct a robot-usable PrimerReagent from an abstract Primer. You can reuse “old” aliquots by passing primer.prepared volume > 0. If no primer.prepared volume is passed, it will be prepared.

Parameters:
  • primer
  • primer_rack
  • pos
  • initial_vol
  • PCR_conc
  • stk_conc
  • def_liq_class
  • fill_limit_aliq
  • excess
class reagent.Reaction(name, labware, components: [<class 'reagent.Reagent'>] = None, track_sample=None, pos=None, num_of_aliquots=1, def_liq_class=None, excess=None, initial_vol=0)[source]

Bases: reagent.Reagent

todo: make this a MixReagent, with diluent too ?

__init__(name, labware, components: [<class 'reagent.Reagent'>] = None, track_sample=None, pos=None, num_of_aliquots=1, def_liq_class=None, excess=None, initial_vol=0)[source]

This is a named set of aliquots of an homogeneous solution. Put a reagent into labware wells, possible distributed into aliquots and set the amount to be used for each sample, if applicable. Each reagent is added to a list of reagents of the worktable were the labware is. The specified excess in % will be calculated/expected. A default excess of 4% will be assumed if None is indicated. A minimal needed volume will be calculated based on either the number of samples and the volume per sample to use or the volume per single use. This can be forced setting min_vol. A minimal number of replicas (wells, aliquots) will be calculated based on the minimal volume, taking into account the maximum allowed volume per well and the excess specified. Aliquots will be filled not more than the percent of the well volumen indicated by fill_limit_aliq.

Parameters:
  • name – Reagent name. Ex: “Buffer 1”, “forward primer”, “IC MS2”
  • labwarelabware.Labware or his label in the worktable; if None will be deduced from wells.
  • volpersample – how much is needed per sample, if applicable, in uL
  • single_use – Not a “per sample” multiple use? Set then here the volume for one single use
  • wells – or offset to begging to put replica. If None will try to assign consecutive wells in labware
  • num_of_aliquots – def min_num_of_replica(), number of replicas
  • def_liq_class – the name of the Liquid class, as it appears in your own EVOware database. instructions.def_liquidClass if None

:param excess; in % :param initial_vol: is set for each replica. If default (=None) is calculated als minimum. :param min_vol: force a minimum volume to be expected or prepared. :param fill_limit_aliq: maximo allowed volume in % of the wells capacity :param num_of_samples: if None, the number of samples of the current protocol will be assumed :param minimize_aliquots: use minimal number of aliquots? Defaults to Reagent.use_minimal_number_of_aliquots,

This default value can be temporally change by setting that global.
class reagent.Reagent(name: str, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, volpersample: float = 0.0, num_of_samples: int = None, single_use: float = None, excess: float = None, initial_vol: (<class 'float'>, <class 'list'>) = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]

Bases: object

A Reagent is a fundamental concept in RobotEvo programming. It makes possible to define a protocol in a natural way, matching what a normal laboratory’s protocol indicates. Defines a named homogeneous liquid solution, the wells it occupy, the initial amount needed to run the protocol (auto calculated), and how much is needed per sample, if applicable. It is also used to define samples, intermediate reactions and products. It makes possible a robust tracking of all actions and a logical error detection, while significantly simplifying the programming of non trivial protocols.

__init__(name: str, labware: (<class 'EvoScriPy.labware.Labware'>, <class 'str'>, []) = None, wells: (<class 'int'>, [<class 'int'>], [<class 'EvoScriPy.labware.Well'>]) = None, num_of_aliquots: int = None, minimize_aliquots: bool = None, def_liq_class: (<class 'str'>, (<class 'str'>, <class 'str'>)) = None, volpersample: float = 0.0, num_of_samples: int = None, single_use: float = None, excess: float = None, initial_vol: (<class 'float'>, <class 'list'>) = 0.0, min_vol: float = 0.0, fill_limit_aliq: float = 100, concentration: float = None)[source]

This is a named set of aliquots of an homogeneous solution. Put a reagent into labware wells, possible distributed into aliquots and set the amount to be used for each sample, if applicable. Each reagent is added to a list of reagents of the worktable were the labware is. The specified excess in % will be calculated/expected. A default excess of 4% will be assumed if None is indicated. A minimal needed volume will be calculated based on either the number of samples and the volume per sample to use or the volume per single use. This can be forced setting min_vol. A minimal number of replicas (wells, aliquots) will be calculated based on the minimal volume, taking into account the maximum allowed volume per well and the excess specified. Aliquots will be filled not more than the percent of the well volumen indicated by fill_limit_aliq.

Parameters:
  • name – Reagent name. Ex: “Buffer 1”, “forward primer”, “IC MS2”
  • labwarelabware.Labware or his label in the worktable; if None will be deduced from wells.
  • volpersample – how much is needed per sample, if applicable, in uL
  • single_use – Not a “per sample” multiple use? Set then here the volume for one single use
  • wells – or offset to begging to put replica. If None will try to assign consecutive wells in labware
  • num_of_aliquots – def min_num_of_replica(), number of replicas
  • def_liq_class – the name of the Liquid class, as it appears in your own EVOware database. instructions.def_liquidClass if None

:param excess; in % :param initial_vol: is set for each replica. If default (=None) is calculated als minimum. :param min_vol: force a minimum volume to be expected or prepared. :param fill_limit_aliq: maximo allowed volume in % of the wells capacity :param num_of_samples: if None, the number of samples of the current protocol will be assumed :param minimize_aliquots: use minimal number of aliquots? Defaults to Reagent.use_minimal_number_of_aliquots,

This default value can be temporally change by setting that global.
init_vol(num_samples=None, initial_vol=None)[source]

To initialize the among of reagent in each well. First put what the user inform he had put, then put additionally the minimum the protocol need. :param num_samples: :param initial_vol: :return:

min_num_of_replica(num_of_samples: int = None) → int[source]

A minimal number of replicas (wells, aliquots) will be calculated based on the minimal volume, taking into account the maximum allowed volume per well and the excess specified. :param num_of_samples: :return:

min_vol(num_samples=None, volume: float = None, add_volume: float = None) → float[source]

A minimal volume will be calculated based on either the number of samples and the volume per sample to use (todo or the volume per single use.)??? :param num_samples: :return:

need_vol = None

calculated volume needed during the execution of the protocol

put_min_vol(num_samples=None)[source]

Force you to put an initial volume of reagent that can be used to distribute into samples, aspiring equal number of complete doses for each sample from each replica, exept the firsts replicas that can be used to aspirate one more dose for the last/rest of samples. That is: all replica have equal volumen (number) of doses or the firsts have one more dose :param num_samples: :return: