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 PCRsPCRMasterMix
: like an item in some table summarizing PCR Master Mixes for some PCR experimentPCReaction
: like an item in some table summarizing reactions in a PCR experimentPCRexperiment
: like an item in some table summarizing PCR experiments
Robot classes:¶
Reagent
: homogeneous liquid solution in some wellsMixReagent
: a Reagent composed of other ReagentsDilution
PreMixReagent
: A pre-MixReagent of otherwise independent reagentsPrimerReagent
: Manipulate a Primer Reagent on a robot.PrimerMixReagent
: Manipulate a Primer-Mix Reagent on a robot.PCRMasterMixReagent
: Manipulate a PCR Master-Mix Reagent on a robot.PCReactionReagent
PCRexperimentRtic
: Organize a PCR setup on a robot.
-
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.
-
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 ?
-
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.
-
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
-
-
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
-
class
reagent.
PCReactionReagent
(pcr_reaction: reagent.PCReaction, plate: EvoScriPy.labware.Labware)[source]¶ Bases:
reagent.Reaction
-
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”
- pcr_exp – [
-
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
-
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
-
-
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
-
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”
- labware –
labware.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”
- labware –
labware.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:
-