Autoprotocol Utils documentation¶
Autoprotocol Utilities are helper functions and modules to generate autoprotocol faster and include on-the-fly verifications. It can only be used in conjunction with autoprotocol-python and automatically installs its required version.
General Helper Functions¶
user_errors_group¶
-
autoprotocol_utilities.misc_helpers.
user_errors_group
(error_msgs, info=None)[source]¶ Takes a list error messages and neatly displays as a single UserError
Will automatically remove instances of None and only report errors if list is not empty.
Parameters: error_msgs (list) – List of strings that are the error messages Raises: ValueError
– If error_msgs is not of type list
char_limit¶
-
autoprotocol_utilities.misc_helpers.
char_limit
(label, length=22, trunc=False, clip=False)[source]¶ Enforces a string limit on the label provided
Can either throw an error message if length is exceeded or correct the string and return the corrected string.
Parameters: - label (str) – String to test.
- length (int, optional) – Maximum label length for this string. Default: 22.
- trunc (bool, optional) – Truncate the label if it is too long. Default: False.
- clip (bool, optional) – Clip the label (remove from beginning of the string) if it is too long Default: False. If both trunc and clip are True, trunc will take effect and not clip.
Returns: label (str) and error_message (string) that is empty on success label is the unmodified, truncated to clipped label as indicated
Return type: namedtuple
Raises: ValueError
– If label is not of type string
det_new_group¶
-
autoprotocol_utilities.misc_helpers.
det_new_group
(i, base=0)[source]¶ Determine if new_group should be added to pipetting operation.
Helper to determine if new_group should be added. Returns true when ‘i’ matches the base, which defaults to 0.
Parameters: - i (int) – The iteration you are on.
- base (int, optional) – The value at which you want to trigger a new group. Default: 0.
Returns: True if iteration equals base case.
Return type: bool
Raises: ValueError
– If i is not of type integerValueError
– If base is not of type integer
printdatetime¶
printdate¶
make_list¶
-
autoprotocol_utilities.misc_helpers.
make_list
(my_str, integer=False)[source]¶ Return a list of strings (or ints) from a string containing comma separated elements.
Parameters: - my_str (str) – String with individual elements separated by comma.
- interger (bool) – If true list of integers instead of list of strings is returned. Default: False.
Returns: List of strings or integers
Return type: list
Raises: ValueError
– If my_str is not of type string
flatten_list¶
-
autoprotocol_utilities.misc_helpers.
flatten_list
(l)[source]¶ Flatten a list recursively without for loops or additional modules
Example Usage:
from autoprotocol_utilities.misc_helpers import flatten_list l = [-1, 0, [1,2], "string", [3, [4, 5]]] flatten_list(l)
Returns:
[-1, 0, 1, 2, 'string', 3, 4, 5]
Parameters: l (list, list of WellGroup) – List or list of WellGroups to flatten Returns: Flat list Return type: list Raises: ValueError
– If l is not of type list
recursive_search¶
-
autoprotocol_utilities.misc_helpers.
recursive_search
(params, class_name=None, method=None, args={})[source]¶ Recursive params checker
Iterates through all items of a passed in dict, tuple, or list and either returns everything as a list, returns an optional subset of them or calls a specified method on the subset
Example Usage:
from autoprotocol.protocol import Protocol from autoprotocol.container import Well from autoprotocol_utilities import recursive_search p = Protocol() example_container = p.ref(name="example", id=None, cont_type="96-pcr", storage="ambient") p.dispense(ref=example_container, reagent="water", columns=[{"column": 0, "volume": "20:microliters"}, {"column": 1, "volume": "10:microliters"} ]) wells = example_container.wells_from(start=0, num=9, columnwise=True) recursive_search(params=wells.wells, class_name=Well, method=volume_check, args={"usage_volume": 15})
Returns:
["1 volume errors: You want to pipette 15.0 ul from a container with " "3.0 ul dead volume (18.0 ul total). However, your aliquot: example-1," "only has 10.0 ul."]
Parameters: - params (list, tuple or dict) – Structure to parse
- class_name (Class name, optional) – Optionally return only instances of a class.
- method (function, optional) – A function that will be applied to all instances found of a class, must include class name.
- args (parameters, optional) – Parameters to pass to a method, if desired.
Returns: Will return a list of all items, or the found items of a specified class, or the response (if not None) from a method called on found items.
Return type: list
Resource Helper Functions¶
ResourceIDs¶
-
class
autoprotocol_utilities.resource_helpers.
ResourceIDs
[source]¶ Common resource ids
A list of resource identification numbers used to provision resources using Autoprotocol.
Example
from autoprotocol-utilities import ResourceIDs res = ResourceIDs() res.water res.te res.zymo_10b res.zymo_dh5a res.zymo_jm109 res.ampicillin_100mg_ml res.chloramphenicol_34mg_ml res.kanamycin_50mg_ml res.mytaq_poly res.dpn_neb res.phusion_poly res.orange_g_100 res.orange_g_500
Returns: resource id of the reagent Return type: str
ResourceIDs methods¶
-
ResourceIDs.
bacteria
(bact=None)[source]¶ Return competent bacteria id
Parameters: bact (string) – Bacteria name, one of: ‘Zymo 10B’, ‘Zymo DH5a’, ‘Zymo JM109’ Returns: resource id for the bacteria requested, None if bact could not be found Return type: string
-
ResourceIDs.
diluents
(dil=None)[source]¶ Return diluent id
Parameters: dil (string) – Diluent name, one of: ‘water’, ‘TE’ Returns: resource id for the diluent requested, None if dil could not be found Return type: string
-
ResourceIDs.
transformation_controls
(media=None)[source]¶ Return transformation controls
Parameters: media (string) – Media for which to select the control. One of: ‘lb_miller_50ug_ml_kan’, ‘lb_miller_100ug_ml_amp’ Returns: resource id for the positive control requested, None if media could not be found Return type: string
-
ResourceIDs.
t4_ligase
(ligase_type=None)[source]¶ Return T4 ligase reagents
Parameters: media (string) – Vendor to use. ‘neb’ or ‘thermo’. Returns: ‘buffer’ - resource id for the buffer ‘ligase’ - resource id for the ligase Return type: dict
-
ResourceIDs.
restriction_enzyme_buffers
(enzyme)[source]¶ Returns a tuple of enzyme_id and buffer_id for a given enzyme
Restriction enzymes need to be digested with a certain buffer. This function returns the correct resource id for the enzyme as well as for the matching buffer.
Parameters: enzyme (string) – name of enzyme, all lower caps such as dpni_neb or ncoi_hf Returns: enzyme_id, buffer_id, errors Return type: namedtuple
oligo_scale_default¶
-
autoprotocol_utilities.resource_helpers.
oligo_scale_default
(length, scale, label)[source]¶ Detects if the oligo length matches the selected scale
Every oligo provider has a length limit on the oligos based on the selected scale. The larger the scale, the longer or shorter the oligo can be. This function checks for IDT limits
Parameters: - length (int) – Length of the oligo in question.
- scale (str) – Scale of the oligo in question.
- label (str) – Name of the oligo.
Returns: ‘success’ (bool) and ‘error_message’ (string) that is empty upon success
Return type: namedtuple
oligo_dilution_table¶
-
autoprotocol_utilities.resource_helpers.
oligo_dilution_table
(conc=None, sc=None)[source]¶ Return dilution table
Determine the amount of diluent to add to an oligo based on concentration wanted and scale ordered. This function can return the entire dilution table or slices and values as needd
Example Usage:
oligo_dilution_table(conc="100uM") oligo_dilution_table(conc="100uM", scale="25nm")
Returns:
{"100uM": {"10nm":60, "25nm": 250, "100nm": 1000, "250nm": 2500, "1um": 10000}} 250
Parameters: - conc (str, optional) – The concentration you wish to select for. Currently 100uM or 1mM.
- sc (str, optional) – The scale you wish to select for. Currently ‘10nm’, ‘25nm’, ‘100nm’, ‘250nm’ or ‘1um’.
Returns: - int – If concentration and scale are given this returns the dilution volume only
- dict – If only one of concentration or scale is provided this function returns a dict. If a concentration is selected it returns a dict where scales are the keys and dilution volumes the values. If a scale is selected it returns a dict with concentrations as keys and dicts of scale (key) and dilution volume (value). If nothing is selected the full dict of concentrations with dicts of scales and dilution volumes is returned.
Raises: ValueError
– If conc is not a valid concentration: ‘100uM’, ‘1mM’ValueError
– If sc is is not a valid scale: ‘10nm’, ‘25nm’, ‘100nm’, ‘250nm’, ‘1um’
return_dispense_media¶
-
autoprotocol_utilities.resource_helpers.
return_dispense_media
()[source]¶ Returns a dict of media for reagent dispenser.
Example Usage:
from autoprotocol.protocol import Protocol from autoprotocol-utilities import return_dispense_media p = Protocol() media = return_dispense_media()["50_ug/ml_Kanamycin"] plate = p.ref("myplate", cont_type="96-flat", discard=True) p.dispense_full_plate(plate, media, "200:microliter")
{ "refs": { "myplate": { "new": "96-flat", "discard": True } }, "instructions": [ { "reagent": "lb_miller_50ug_ml_kan", "object": "myplate", "columns": [ { "column": 0, "volume": "200:microliter" }, { "column": 1, "volume": "200:microliter" }, { "column": 2, "volume": "200:microliter" }, { "column": 3, "volume": "200:microliter" }, { "column": 4, "volume": "200:microliter" }, { "column": 5, "volume": "200:microliter" }, { "column": 6, "volume": "200:microliter" }, { "column": 7, "volume": "200:microliter" }, { "column": 8, "volume": "200:microliter" }, { "column": 9, "volume": "200:microliter" }, { "column": 10, "volume": "200:microliter" }, { "column": 11, "volume": "200:microliter" } ], "op": "dispense" } ] }
Returns: Media with common display_name as key and identifier for code as value Return type: dict
return_agar_plates¶
-
autoprotocol_utilities.resource_helpers.
return_agar_plates
(wells=6)[source]¶ Returns a dict of all available agar plates.
Parameters: wells (integer) – Integer of the number of wells in the plate, 1 or 6. Default: 6 for 6-well plate Returns: plates with plate identity as key and kit_id as value Return type: dict Raises: ValueError
– If wells is not a integer equal to 1 or 6
ref_kit_container¶
-
autoprotocol_utilities.resource_helpers.
ref_kit_container
(protocol, name, container, kit_id, discard=True, store=None)[source]¶ Reserve agar plates for use within a protocol.
In use only to allow booking of agar plates within a protocol.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import return_dispense_media, return_agar_plates, ref_kit_container p = Protocol() bacteria = p.ref(name="test_bact", id=None, cont_type="micro-1.5", discard=True).well(0) media = return_dispense_media()["50_ug/ml_Kanamycin"] agar_id = return_agar_plates(1)[media] agar_plate = ref_kit_container(p, "my_agar_plate", "6-flat", agar_id, discard=False, store="cold_4")
Parameters: - protocol (Protocol) – instance of protocol.
- name (str) – Name for the plate.
- container (str) – Container type name.
- kit_id (str) – Kit item to be created.
- discard (bool) – Determine if plate is discarded after use.
- store (str) – If the plate is not discarded, indicate valid storage condition.
Returns: Return type: Container
Container Helper Functions¶
volume_check¶
-
autoprotocol_utilities.container_helpers.
volume_check
(well, usage_volume=0, use_safe_vol=False, use_safe_dead_diff=False)[source]¶ Basic Volume check
Checks to see if the designated well has usage_volume above the well’s dead volume. In other words, this method checks if usage_volume can be pipetted out of well.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities.container_helpers import volume_check p = Protocol() example_container = p.ref(name="exampleplate", id=None, cont_type="96-pcr", storage="warm_37") p.dispense(ref=example_container, reagent="water", columns=[{"column": 0, "volume": "10:microliters"}]) #Checks if there are 5 microliters above the dead volume #available in well 0 assert (volume_check(well=example_container.well(0), usage_volume=5)) is None #Checks if the volume in well 0 is at least the safe minimum volume assert (volume_check(well=example_container.well(0), usage_volume=0, use_safe_vol=True) is None
Parameters: - well (Well, WellGroup, list) – Well(s) to test
- usage_volume (Unit, str, int, float, optional) – Volume to test for. If 0 the aliquot will be tested against the container dead volume. If int or float is used, microliter will be assumed.
- use_safe_vol (bool, optional) – Use safe minimum volume instead of dead volume
- use_safe_dead_diff (bool, optional) – Use the safe_minimum_volume - dead_volume as the required amount. Useful if set_pipettable_volume() was used before to correct the well_volume to not include the dead_volume anymore
Returns: - str – string of errors if volume check failed OR
- None – If no errors are detected
Raises: ValueError
– If well is not of type Well, list or WellGroupValueError
– If elements of well are not of type Well
set_pipettable_volume¶
-
autoprotocol_utilities.container_helpers.
set_pipettable_volume
(well, use_safe_vol=False)[source]¶ Remove dead volume from pipettable volume.
In one_tip true pipetting operations the volume of the well is used to determine who many more wells can be filled from this source well. Thus it is useful to remove the dead_volume (default), or the safe minimum from the set_volume of the well. It is recommeneded to remove the dead_volume only and check for safe_vol later.
Parameters: - well (Container, WellGroup, list, Well) – Well to set.
- use_safe_vol (bool, optional) – Instead of removing the indicated dead_volume, remove the safe minimum volume.
Returns: Will return the same type as was received
Return type: Container, WellGroup, list, Well
well_name¶
-
autoprotocol_utilities.container_helpers.
well_name
(well, alternate_name=None, humanize=False)[source]¶ Determine new well name
Determine the name for a new well based on passed well.
Parameters: - well (Well) – Well to source original name, index properties.
- alternate_name (str, optional) – If this parameter is passed and the well does not have a name, this name will be returned instead of the container name, appended with the well index.
Returns: well name in the format name if the well had a name or name-index if the name is derived from the container name or alternate_name
Return type: str
Raises: ValueError
– If well is not of type WellValueError
– It alternate_name is not of type string
plates_needed¶
-
autoprotocol_utilities.container_helpers.
plates_needed
(wells_needed, wells_available)[source]¶ Takes wells needed as a numbers (int or float) and wells_available as a container, container type string or a well number (int or float) and calculates how many plates are needed to accomodate the wells_needed.
Parameters: - wells_needed (float, int) – How many you need
- wells_available (Container, float, int, string) – How many you have available per unit. If container or a string identifying a container type, then all wells of this container will be considered
Returns: How many of unit you will need to accomodate all wells_needed
Return type: int
Raises: RuntimeError
– If wells_needed is not of type integer or floatRuntimeError
– If wells_available is not of type integer or float or Container
sort_well_group¶
-
autoprotocol_utilities.container_helpers.
sort_well_group
(wells, columnwise=False)[source]¶ Sort a well group in rowwise or columnwise format.
This function sorts first by container id and name, then by row or column, as needed. This function is useful to sort a list of wells passed in an unknown order (eg. user entered).
Parameters: - wells (list, WellGroup) – List of wells to sort.
- columnwise (bool, optional) –
Returns: Sorted list of wells
Return type: WellGroup
Raises: ValueError
– If wells are not of type list or WellGroupValueError
– If elements of wells are not of type well
is_columnwise¶
-
autoprotocol_utilities.container_helpers.
is_columnwise
(wells)[source]¶ Detect if input wells are in a columnwise format.
This function only triggers if the first column is full and only a consecutive fractionally filled columns exist. It is used to determine whether columnwise should be used in a pipette operation.
Only accepts wells that belong to 1 container. Use unique_containers or get_well_list_by_cont to assure you submit only wells from one container.
Patterns detected (4x6 plate):
x x | x x x | x | x x | x x x | x | x x | x x x | x | x x | x x x | x |
Patterns NOT detected (4x6 plate):
x x x | x | x x | x | x x | x | x x | x x x |
Example Usage:
from autoprotocol.protocol import Protocol from autoprotocol_utilities import is_columnwise p = Protocol() plate = p.ref("plate", None, cont_type="96-flat", storage="cold_4", cover="standard") col_wells = plate.wells_from(start="A1", num=17, columnwise=True) col_wells_2 = plate.wells_from(start="A2", num=17, columnwise=True) row_wells = plate.wells_from(start="A1", num=17, columnwise=False) rand_wells = plate.wells("A2", "B12", "H7") is_columnwise(col_wells) is_columnwise(col_wells_2) is_columnwise(row_wells) is_columnwise(rand_wells)
Returns:
True True False False
Parameters: wells (Well, list, WellGroup) – List of wells or well_group containing the wells in question.
Returns: - bool – True if columnwise. False if rowwise.
- list – List of strings if errors were encountered.
Raises: ValueError
– If wells are not of type Well, list or WellGroupValueError
– If elements of wells are not of type Well
unique_containers¶
-
autoprotocol_utilities.container_helpers.
unique_containers
(wells)[source]¶ Get unique containers
Get a list of unique containers for a list of wells
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import get_well_list_by_cont p = Protocol() wells_1 = p.ref("plate_1_96", None, "96-flat", discard=True).wells_from("A1", 12) wells_2 = p.ref("plate_2_96", None, "96-flat", discard=True).wells(0, 24, 49) wells_3 = p.ref("plate_3_96", None, "96-flat", discard=True).well("D3") many_wells = wells_1 + wells_2 + wells_3 unique_containers(many_wells)
Returns:
[Container(plate_1_96), Container(plate_3_96), Container(plate_2_96)]
Parameters: wells (Well, list, WellGroup) – List of wells. Returns: List of Containers Return type: list Raises: ValueError
– If wells are not of type list or WellGroup
first_empty_well¶
-
autoprotocol_utilities.container_helpers.
first_empty_well
(wells, return_index=True)[source]¶ Get the first empty well of a container followed by only empty wells
Parameters: - wells (Container, WellGroup, list) – Can accept a container, WellGroup or list of wells.
- return_index (bool, optional) – Default true, if true returns the index of the well, if false the well itself.
Returns: - well – The first empty well OR
- int – The index of the first empty well when return_index=True OR
- None – when no empty well was found.
Raises: ValueError
– If wells are not of type list, WellGroup or Container
list_of_filled_wells¶
-
autoprotocol_utilities.container_helpers.
list_of_filled_wells
(wells, empty=False)[source]¶ For the container given, determine which wells are filled
Parameters: - wells (Container, WellGroup, list) – Takes a container (uses all wells), a WellGroup or a List of wells
- empty (bool) – If True return empty wells instead of filled
Returns: list of wells
Return type: list
Raises: ValueError
– If wells are not of type list, WellGroup or Container
container_type_checker¶
-
autoprotocol_utilities.container_helpers.
container_type_checker
(containers, shortname, exclude=False)[source]¶ Verify container is of specified container_type.
Parameters: - containers (Container, list) – Single Container or list of Containers
- shortname (str, list of str) – Short name used to specify ContainerType.
- exclude (bool, optional) – Verify container is NOT of specified container_type.
Returns: - str – String of containers failing container_type_check OR
- None – If no container fails
Raises: ValueError
– If an unknown ContainerType shortname is passed.ValueError
– If an containers are not of type Container.
get_well_list_by_cont¶
-
autoprotocol_utilities.container_helpers.
get_well_list_by_cont
(wells)[source]¶ Get wells sorted by container
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import get_well_list_by_cont p = Protocol() wells_1 = p.ref("plate_1_96", None, "96-flat", discard=True).wells_from("A1", 12) wells_2 = p.ref("plate_2_96", None, "96-flat", discard=True).wells(0, 24, 49) wells_3 = p.ref("plate_3_96", None, "96-flat", discard=True).well("D3") many_wells = wells_1 + wells_2 + wells_3 get_well_list_by_cont(many_wells)
Returns:
{ Container(plate_1_96): [ Well(Container(plate_1_96), 0, None), Well(Container(plate_1_96), 1, None), Well(Container(plate_1_96), 2, None) ], Container(plate_3_96): [ Well(Container(plate_3_96), 38, None) ], Container(plate_2_96): [ Well(Container(plate_2_96), 0, None), Well(Container(plate_2_96), 24, None), Well(Container(plate_2_96), 49, None) ] }
Parameters: wells (list, WellGroup) – The list of wells to be sorted by the containers that they are in
Returns: Dict with containers as keys and List of wells as value
Return type: dict
Raises: ValueError
– If wells is not of type list or WellGroupValueError
– If elements of wells are not of type Well
stamp_shape¶
-
autoprotocol_utilities.container_helpers.
stamp_shape
(wells, full=True, quad=False)[source]¶ Determine if a list of wells is stampable
Find biggest reactangle that can be stamped from a list of wells. Can be any rectangle, or enforce full row or column span. If a list of wells from a container that cannot be stamped is provided, all wells will be returned in remaining_wells of the stamp shape.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import stamp_shape, first_empty_well, flatten_list p = Protocol() plate = p.ref("myplate", cont_type="96-pcr", storage="cold_4") dest_plate = p.ref("newplate", cont_type="96-pcr", storage="cold_4") src_wells = plate.wells_from(0, 40) shape = stamp_shape(src_wells) remaining_wells = [] for s in shape: p.stamp(s.start_well, dest_plate.well(0), "10:microliter", s.shape) remaining_wells.append(s.remaining_wells) next_dest = first_empty_well(dest_plate) remaining_wells = flatten_list(remaining_wells) p.transfer(remaining_wells, dest_plate.wells_from(next_dest, len(remaining_wells)), "10:microliter" )
Autoprotocol Output:
{ "refs": { "myplate": { "new": "96-pcr", "store": { "where": "cold_4" } }, "newplate": { "new": "96-pcr", "store": { "where": "cold_4" } } }, "instructions": [ { "groups": [ { "transfer": [ { "volume": "10.0:microliter", "to": "newplate/0", "from": "myplate/0" } ], "shape": { "rows": 3, "columns": 12 }, "tip_layout": 96 } ], "op": "stamp" }, { "groups": [ { "transfer": [ { "volume": "10.0:microliter", "to": "newplate/36", "from": "myplate/36" } ] }, { "transfer": [ { "volume": "10.0:microliter", "to": "newplate/37", "from": "myplate/37" } ] }, { "transfer": [ { "volume": "10.0:microliter", "to": "newplate/38", "from": "myplate/38" } ] }, { "transfer": [ { "volume": "10.0:microliter", "to": "newplate/39", "from": "myplate/39" } ] } ], "op": "pipette" } ] }
Parameters: - wells (Container, WellGroup, list) – If Container - all filled wells will be used to determine the shape. If list of wells or well_group all provided wells will be analyzed.
- full (bool, optional) – If true will only return shapes that span either the full rows or columns of the container.
- quad (bool, optional) – Set to true if you want to get the stamp shape for a 384 well testing all quadrants. False is used for determining col- vs row-wise. True is used to initiate the correct stamping.
Returns: - list – contains namedtuples where each tuple has the following parameters
- start_well (well) – is the top left well for the source stamp group
- shape (dict) – is a dict of rows and columns describing the stamp shape
- remainging_wells (list) – is a list of wells that are not included in the stamp shape
- included_wells (list) – is a list of wells that is included in the stamp shape
Raises: RuntimeError
– If wells are not of type list or WellGroupValueError
– If elements of wells are not of type wellValueError
– If wells are not from one container only
next_wells¶
-
autoprotocol_utilities.container_helpers.
next_wells
(target, num=1, columnwise=False)[source]¶ Given a plate, a list of plates or a WellGroup, returns a generator function that can be used to iterate through the (container’s) wells.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import next_wells p = Protocol() c1 = p.ref("c1", id=None, cont_type="96-pcr", discard=True) assay_wells = next_wells(c1, num=2, columnwise=False) my_wells = [] your_wells = [] my_wells.extend(next(assay_wells)) your_wells.extend(next(assay_wells)) your_wells.extend(next(assay_wells)) your_wells
Returns:
[ Well(Container(c1), 2, None), Well(Container(c1), 3, None), Well(Container(c1), 4, None), Well(Container(c1), 5, None) ]
Parameters: - target (Container, List of Containers, WellGroup) – The generator will iteratively return wells from these plate(s) or WellGroup, in order, from the first well in the list, based on the parameters below.
- num (int, optional) – The generator will produce this many wells with each iteration. Defaults to 1.
- columnwise (bool, optional) – Set to True if wells should be generated in columnwise format. Defaults to False. If a WellGroup is given this parameter is ignored.
Returns: This function will iteratively generate the next set of wells from the plate. Get the next plates using next(generator). Wells will be returned as a WellGroup.
Return type: generator
Raises: ValueError
– If target is not a Container, a list of Containers or a WellGroupStopIteration
– If all wells have been used
Rectangle helper functions¶
-
autoprotocol_utilities.rectangle.
area
(rect)[source]¶ Computes geometrical area for Areas and Rects
Parameters: rect (Area, Rect, Namedtuple) – Object that needs area calculation done Returns: The area of the object Return type: int
-
autoprotocol_utilities.rectangle.
area2rect
(area, row_idx)[source]¶ Converts an Area (no y coord) into a Rect. The y coord of the top left of the Rect is derived from the area height and the row_idx.
Parameters: - area (Area, Rect, Namedtuple) – Object that needs area calculation done
- row_idx (int) – The row index of the area
Returns: A rectangle object with width, height, x, and y
Return type: Rectangle
-
autoprotocol_utilities.rectangle.
max_histogram_area
(histogram)[source]¶ Find height, width of the largest rectangle that fits entirely under the histogram. Algorithm is “Linear search using a stack of incomplete subproblems” [1]. [1]: http://blog.csdn.net/arbuckle/archive/2006/05/06/710988.aspx
Parameters: histogram (list) – The histogram that the method will find the largest rectangle within Returns: The maximum area of the given histogram Return type: Area
-
autoprotocol_utilities.rectangle.
binary_list
(wells, length=None)[source]¶ Turns a list of indices into a binary list with list at indices that appear in the initial list set to 1, and 0 otherwise. wells must be sorted, length is the length of the resulting list.
[bnry for bnry in binary_list([1, 3, 5], length=7)] [0, 1, 0, 1, 0, 1, 0]
Parameters: - wells (Sorted list) – The wells that need to be changed into a binary list
- length (Int) – The length of the total list
Returns: Turns wells into a binary list
Return type: None
-
autoprotocol_utilities.rectangle.
get_quadrant_indices
(quad)[source]¶ Return a list of well indices that correspond to the correct quadrant on a 384 well plate
Parameters: quad (Int) – The wells that need to be changed into a binary list Returns: All the wells inside the desired quadrant Return type: List
-
autoprotocol_utilities.rectangle.
get_quadrant_binary_list
(binary_list, quad=[0, 1, 2, 3])[source]¶ Take a binary list of 384 elements (aka wells) and return all the wells in the designated quadrant. This will be the stampable 96 wells that we have to check for a rectangle.
Parameters: - binary_list (List) – The 384 element well plate
- quad (list) – The quadrants to look in, the values can be: 0,1,2,3
Returns: A list filled with smaller lists, separating each set of wells into quadrants
Return type: List of lists
-
autoprotocol_utilities.rectangle.
get_well_in_quadrant
(quadwells, quad)[source]¶ Take a list of wells and quadrant and return the correct well index in the 384 plate
Parameters: - quadwells (list) – The wells in question
- quad (Int) – The quadrant the well is in
Returns: Returns the correct well indices of all the quad-specific wells in quadwells
Return type: List
-
autoprotocol_utilities.rectangle.
chop_list
(lst, chop_length, filler=None)[source]¶ Chops a list into a list of lists. Used to generate a plate map corresponding to microplate layouts.
Parameters: - lst (list) – The original list that needs to be chopped up
- chop_length (Int) – The length of the pieces to chop the big list into
- filler (Int, optional) – The stuff to fill up the leftover pieces
Returns: Returns the correct well indices of all the quad-specific wells in quadwells
Return type: List
Magnetic Bead Separation Helper Functions¶
get_mag_amplicenter¶
-
autoprotocol_utilities.magnetic_helpers.
get_mag_amplicenter
(plate, amplitude_fraction=1.0)[source]¶ Determine amplitude and center for KF operations
Given the container this function determines the well type and fill volume. From that it calculates the center for the magnetic operation (1/2 the fill volume) and the amplitude to move around that from 0 to center + amplitude.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities.magnetic_helpers import get_mag_amplicenter p = Protocol() example_plate = p.ref(name="Example", id=None, cont_type="96-pcr", storage="ambient") p.dispense(ref=example_plate, reagent="water", columns=[{"column": 4, "volume": "100:microliters"},]) get_mag_amplicenter(example_plate)
Returns:
{'center': 0.3125, 'amplitude': 0.3125}
Parameters: - plate (Container) – Plate that is being used
- amplitude_fraction (float, optional) – By default the full available amplitude will be used (from center to bottom of well). Use this parameter to reduce the amplitude.
Returns: center and amplitude both of type float
Return type: nametuple
Raises: ValueError
– If plate is not of type ContainerValueError
– If amplitude_fraction is not a float or bigger than 1
get_mag_frequency¶
-
autoprotocol_utilities.magnetic_helpers.
get_mag_frequency
(plate, speed)[source]¶ Determine frequency for KF operation
Based on plate type and the desired KF speed, determine the frequency for the KF operation. Needed for mix and release operations.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities.magnetic_helpers import get_mag_frequency p = Protocol() example_plate = p.ref(name="Example", id=None, cont_type="96-pcr", storage="ambient") get_mag_frequency(plate=example_plate, speed="slow")
Returns:
0.4:hertz
Parameters: - plate (Container) – Container that is being used
- speed (string) – String defining the speed - can be slow, medium, fast
Returns: Frequency in the form of “2.5:Hz”
Return type: string
Raises: ValueError
– If plate is not of type ContainerValueError
– If speed is not ‘slow’, ‘medium’, ‘fast’ValueError
– If plate type is not a key in frequencies
Bio Calculator Functions¶
dna_mass_to_mole¶
-
autoprotocol_utilities.bio_calculators.
dna_mass_to_mole
(length, mass, ds=True)[source]¶ For the DNA Length and mass given, return the mole amount of DNA
Example Usage:
from autoprotocol_utilities import dna_mass_to_mole from autoprotocol.unit import Unit dna_length = 100 dna_mass = Unit(33, 'ng') dna_mass_to_mole(dna_length, dna_mass)
Returns:
Unit(0.5, 'picomole')
Parameters: - length (int) – Length of DNA in bp
- mass (str, Unit) – Weight of DNA in prefix-g
- ds (bool, optional) – True for dsDNA, False for ssDNA
Returns: pmole_dna – Mole amount of DNA in pmol
Return type: Unit
Raises: ValueError
– If inputs are not of specified types
dna_mole_to_mass¶
-
autoprotocol_utilities.bio_calculators.
dna_mole_to_mass
(length, mole, ds=True)[source]¶ For the DNA Length and mole amount given, return the mass of DNA
Example Usage:
from autoprotocol_utilities import dna_mole_to_mass from autoprotocol.unit import Unit dna_length = 5000 dna_mole = "10:pmol" dna_mole_to_mass(dna_length, dna_mole)
Returns:
Unit(33.0, 'microgram')
Parameters: - length (int) – Length of DNA in bp
- mole (str, Unit) – Mole amount of DNA in prefix-mol
- ds (bool, optional) – True for dsDNA, False for ssDNA
Returns: dna_ug – Weight of DNA in ug
Return type: Unit
Raises: ValueError
– If inputs are not of specified types
molar_to_mass_conc¶
-
autoprotocol_utilities.bio_calculators.
molar_to_mass_conc
(length, molar, ds=True)[source]¶ For the DNA molarity given, return the mass concentration of DNA
Example Usage:
from autoprotocol_utilities import molar_to_mass_conc from autoprotocol_utilities import dna_mole_to_mass from autoprotocol.unit import Unit dna_length = 5000 dna_molarity = Unit(10, 'uM') molar_to_mass_conc(dna_length, dna_molarity)
Returns:
Unit(33000.0, 'nanogram / microliter')
Parameters: - length (int) – Length of DNA in bp
- molar (str, Unit) – Molarity of DNA in prefix-M
- ds (bool, optional) – True for dsDNA, False for ssDNA
Returns: mass_conc – Mass concentration of DNA in ng/uL
Return type: Unit
Raises: ValueError
– If inputs are not of specified types
mass_conc_to_molar¶
-
autoprotocol_utilities.bio_calculators.
mass_conc_to_molar
(length, mass_conc, ds=True)[source]¶ For the DNA mass concentration given, return the molarity of DNA
Example Usage:
from autoprotocol_utilities import mass_conc_to_molar from autoprotocol_utilities import dna_mass_to_mole from autoprotocol.unit import Unit dna_length = 5000 dna_mass_conc = Unit(33, 'ng/uL') mass_conc_to_molar(dna_length, dna_mass_conc)
Returns:
Unit(0.01, 'micromolar')
Parameters: - length (int) – Length of DNA in bp
- mass_conc (str, Unit) – Mass concentration of DNA
- ds (bool, optional) – True for dsDNA, False for ssDNA
Returns: molar – Molarity of DNA in uM
Return type: Unit
Raises: ValueError
– If inputs are not of specified types
ligation_insert_ng¶
-
autoprotocol_utilities.bio_calculators.
ligation_insert_ng
(plasmid_size, plasmid_mass, insert_size, molar_ratio=1)[source]¶ For the plasmid size, plasmid amount, insert size, and molar ratio given, return the mass of insert needed for ligation
Different from ligation_insert_volume: no insert concentration is given -> returns mass of insert needed
Example Usage:
from autoprotocol_utilities import ligation_insert_ng from autoprotocol.unit import Unit plasmid_size = 3000 plasmid_mass = Unit(100, 'ng') insert_size = 48 ligation_insert_ng(plasmid_size, plasmid_mass, insert_size)
Returns:
Unit(1.6, 'nanogram')
Parameters: - plasmid_size (int) – Length of plasmid in bp.
- insert_size (int) – Length of insert in bp
- plasmid_mass (str, Unit) – Mass of plasmid in prefix-g
- molar_ratio (int, float, string, optional) – Ligation molar ratio of insert : vector. By default it is 1 : 1. Generally ligations are tested at 1:3, 1:1, and 3:1
Returns: insert_amount – Amount of insert solution needed in ng
Return type: Unit
Raises: ValueError
– If wells are not of type list, WellGroup or Container
ligation_insert_volume¶
-
autoprotocol_utilities.bio_calculators.
ligation_insert_volume
(plasmid_size, plasmid_mass, insert_size, insert_conc, ds=True, molar_ratio=1)[source]¶ For the plasmid size, plasmid amount, insert size, insert concentration, and molar ratio given, return the volume of insert solution needed for ligation
Different from ligation_insert_ng: insert concentration is given -> returns volume of insert solution needed
Example Usage:
from autoprotocol_utilities import ligation_insert_volume from autoprotocol_utilities import molar_to_mass_conc from autoprotocol.unit import Unit plasmid_size = 3000 plasmid_mass = Unit(100, 'ng') insert_size = 48 insert_conc = Unit(25, 'ng/uL') ligation_insert_volume(plasmid_size, plasmid_mass, insert_size, insert_conc)
Returns:
Unit(0.064, 'microliter')
Parameters: - plasmid_size (int) – Length of plasmid in bp.
- plasmid_mass (str, Unit) – Mass of plasmid in prefix-g
- insert_size (int) – Length of insert in bp
- insert_conc (str, Unit) – Molar or mass concentration of insert
- ds (bool, optional) – True for dsDNA, False for ssDNA
- molar_ratio (int, float, string, optional) – Ligation molar ratio of insert : vector. Common ratios are 1:3, 1:1, and 3:1. 1:1 by default
Returns: insert_amount – Volume of insert solution needed in uL
Return type: Unit
Raises: ValueError
– If wells are not of type list, WellGroup or Container
ligation_insert_amount¶
-
autoprotocol_utilities.bio_calculators.
ligation_insert_amount
(plasmid_size, plasmid_conc, plasmid_volume, insert_size, insert_conc, ds=True, molar_ratio=1)[source]¶ For the plasmid size, plasmid concentration, insert size, insert concentration, and molar ratio given, return the volume of insert solution needed for ligation
Different form ligation_insert_volume: plasmid concentration and volume are given instead of plasmid mass
Example Usage:
from autoprotocol_utilities import ligation_insert_amount from autoprotocol_utilities import molar_to_mass_conc from autoprotocol.unit import Unit plasmid_size = 2000 plasmid_conc = '1.5:uM' plasmid_volume = Unit(10, 'uL') insert_size = 25 insert_conc = Unit(10, 'ng/uL') ligation_insert_amount(plasmid_size, plasmid_conc, plasmid_volume, insert_size, insert_conc)
Returns:
Unit(24.75, 'microliter')
Parameters: - plasmid_size (int) – Length of plasmid in bp.
- plasmid_conc (str, Unit) – Molar or mass concentration of plasmid solution
- plasmid_volume (str, Unit) – Volume of plasmid solution in prefix-L
- insert_size (int) – Length of insert in bp
- insert_conc (str, Unit) – Molar or mass concentration of insert solution
- ds (bool, optional) – True for dsDNA, False for ssDNA
- molar_ratio (int, float, string, optional) – Ligation molar ratio of insert : vector. Common ratios are 1:3, 1:1, and 3:1. 1:1 by default
Returns: insert_amount – Volume of insert solution in uL
Return type: Unit
Raises: ValueError
– If wells are not of type list, WellGroup or Container
Thermocycling Helper Functions¶
melt_curve¶
-
autoprotocol_utilities.thermocycle_helpers.
melt_curve
(start=65, end=95, inc=0.5, rate=5)[source]¶ Generate a melt curve on the fly
No inputs neded for a standard melt curve.
Example Usage:
from autoprotocol import Protocol from autoprotocol_utilities import melt_curve protocol = Protocol() dest_plate = protocol.ref("plate", None, "96-pcr", discard=True, storage=None) protocol.seal(dest_plate) melt_params = melt_curve() protocol.thermocycle(dest_plate, [{"cycles": 1, "steps": [ {"temperature": "37:celsius", "duration": "60:minute"} ] } ], volume="15:microliter", dataref="data", dyes={"SYBR": dest_plate.wells_from(0, 3).indices()}, **melt_params)
Returns:
{ "refs": { "plate": { "new": "96-pcr", "discard": true } }, "instructions": [ { "object": "plate", "type": "ultra-clear", "op": "seal" }, { "dataref": "data", "melting": { "start": "65.00:celsius", "rate": "5.00:second", "end": "95.00:celsius", "increment": "0.50:celsius" }, "object": "plate", "volume": "15:microliter", "groups": [ { "cycles": 1, "steps": [ { "duration": "60:minute", "temperature": "37:celsius" } ] } ], "dyes": { "SYBR": [ "A1", "A2", "A3" ] }, "op": "thermocycle" } ] }
Parameters: - start (int, float) – Temperature to start at
- end (int, float) – Temperature to end at
- inc (int, float) – Temperature increment during the melt_curve
- rate (int) – After x seconds the temperature is incremented by inc
Returns: melt_params – containing melt_params
Return type: dict
Raises: ValueError
– If start, end or inc are not of type float or int. And if rate is not of type int
thermocycle_ramp¶
-
autoprotocol_utilities.thermocycle_helpers.
thermocycle_ramp
(start_temp, end_temp, total_duration, step_duration)[source]¶ Create a ramp instruction for the thermocyler.
Create a multi-temperature thermocycling program commonly used in annealing protocols. Based on total time and the step duration this function computes the temperature increment required for each step within the start and the end temperature.
Example Usage:
thermocycle_group = [ { "cycles": 1, "steps": thermocycle_ramp(65, 95, "30:minute", "1:minute") } ] protocol.thermocycle(dest_plate, groups=thermocycle_group, volume="15:microliter")
Parameters: - start_temp (string, int, float, Unit) – Start of the thermocycle protocol, in the format “37:celsius”
- end_temp (string, int, float, Unit) – End of the thermocycle protocol, in the format “37:celsius”
- total_duration (string, Unit) – Total duration of the thermocycle protocol, in the format “1:hour”
- step_duration (string, Unit) – Time that each temperature should be held, in the format “1:minute”
Returns: containing thermocycling steps that can be used in the thermocycle instruction
Return type: dict
Raises: ValueError
– If either temperature is not of type int, float, string or Unit and if either duration is not of type string or Unit
Changelog¶
Next 2.x feature release
- [Support]: document fixes and year update
2.3.3 2017-3-21
- [Bug]: Remove unsupported resource ids
2.3.2 2017-1-16
- [Bug]: Fixes bug where next_wells could not be used as an iterator for loops
2.3.1 2016-10-20
- [Bug]: next_wells fails with error and accepts list of Containers
2.3.0 2016-10-10
- [Feature]: Travis-ci and tox checkers added
- [Feature]: added well generator next_wells
- [Support]: fix dox example thermocycle_ramp
2.2.1 2016-09-12
- [Feature]: Travis-ci and tox checkers added
- [Bug]: fix import compatibility for py3
- [Bug]: fixed python2/3 compatibility bugs
- [Support]: fix dox example thermocycle_ramp
2.2.0 2016-07-28
- [Feature]: media types and restriction enzymes
- [Feature]: include positive control reagents for exonuclease assembly kits
- [Feature]: positive control for Gibson assembly
- [Feature]: bio_calculators module
- [Bug]: fix thermocycle_ramp calculations
- [Bug]: sys.path.insert typo in docs/conf.py
- [Support]: documentation improvements
- [Support]: added additional information to oligo scale limit error messages
- [Support]: additonal tests and documentation
- [Support]: more examples to functions
- [Support]: new changelog and improved documentation
2.1.7 2016-06-29
- [Feature]: positive control for Gibson assembly
- [Bug]: flatten_list can flatten WellGroup
2.1.6 2016-06-24
- [Support]: more examples to functions
2.1.5 2016-06-14
- [Feature]: include positive control reagents for exonuclease assembly kits
- [Bug]: Container storage for ref_kit_container
2.1.4 2016-05-11
- [Feature]: media types and restriction enzymes
- [Bug]: unique_containers can properly deal with WellGroups
- [Support]: additonal tests and documentation
2.1.3 2016-04-07
- [Bug]: volume_check now returns consolidated string of errors
- [Bug]: container_type_checker now returns consolidated string of all container errors found
- [Support]: documentation improvements
- [Support]: added additional information to oligo scale limit error messages
2.1.2 2016-04-05
- [Bug]: well_name now takes and argument humanize which results in the index being printed as A1 as opposed to 0
2.1.1 2016-04-05
- [Feature]: add resources for exonuclease and picrogreen assays in Resource Helper Functions
- [Feature]: allow set_pipettable_volume to process wells from many containers
- [Feature]: allow container type strings for wells_available in plates_needed
- [Feature]: magnetic helper functions in Magnetic Bead Separation Helper Functions
- [Feature]: additional resources in Resource Helper Functions
- [Support]: improvements in documentation
2.0.1 2016-03-29
- [Feature]: add resources for exonuclease and picrogreen assays in Resource Helper Functions
- [Feature]: allow set_pipettable_volume to process wells from many containers
- [Support]: improvements in documentation
2.0.0 2016-03-18
- [Feature]: use new unit system (pint) with autoprotocol-python 3.0
- [Feature]: resource id adjustments in Resource Helper Functions
- [Feature]: add restriction_enzyme_buffers method to ResourceIDs
1.5.0 2016-03-11
- [Feature]: rewrite is_columnwise
- [Feature]: unique_containers can also deal with single well
- [Feature]: stamp_shape does not break anymore when presented with a container that is not 96 or 384 well. returns all wells as remaining
- [Feature]: add transformation controls
- [Feature]: renaming some reactangle functions
- [Feature]: stamp_shape also returns included_wells
- [Feature]: stamp_shape now always returns a list. start_well will be of type Well. start_well will be None if no shape is found
- [Feature]: volume_check can accept a list of wells or WellGroup
- [Feature]: transfer_properties
- [Feature]: 10nm scale to oligo_scale_default
- [Feature]: adjust media strings
- [Feature]: t4_ligase() method for ResourceIDs
- [Support]: ligase reagents and better documentation
- [Support]: documentation
1.4.4 2016-03-11
- [Feature]: adjust media strings
- [Feature]: t4_ligase() method for ResourceIDs
- [Support]: documentation
1.4.3 2016-03-06
- [Support]: ligase reagents and better documentation
1.4.2 2016-03-06
- [Feature]: rewrite is_columnwise
- [Feature]: unique_containers can also deal with single well
- [Feature]: stamp_shape does not break anymore when presented with a container that is not 96 or 384 well. returns all wells as remaining
- [Feature]: add transformation controls
- [Feature]: renaming some reactangle functions
- [Feature]: stamp_shape also returns included_wells
- [Feature]: stamp_shape now always returns a list. start_well will be of type Well. start_well will be None if no shape is found
- [Feature]: volume_check can accept a list of wells or WellGroup
- [Feature]: transfer_properties
- [Feature]: 10nm scale to oligo_scale_default
1.4.0 2016-02-28
- [Feature]: user_errors_group optional info parameter
- [Support]: modules - moved to promodules
1.3.0 2016-02-24
- [Feature]: stamp_shape can now deal with 384 plates (quadrants)
- [Feature]: container_type_checker function
- [Bug]: createMastermix Unit input
1.2.0 2016-02-22
- [Feature]: user_errors_group automatically filters out None
- [Bug]: stamp function defaults to only return full row or col stamp
- [Bug]: user_errors_group
1.1.0 2016-02-19
- [Feature]: list_of_filled_wells can take a list of wells or container
- [Feature]: first_empty_well can take a list of wells or container
- [Feature]: recursive_search function
- [Feature]: well_name function
- [Bug]: stray setup.py
1.0.0 2016-02-18
- [Feature]: Initial release
Credits¶
Autoprotocol-utilities is currently maintained by:
- Vanessa Biggers - polarpine - vanessa@transcriptic.com
- Cornelia Scheitz - cojofra - cornelia.scheitz@gmail.com
For more information about Autoprotocol and its specification, visit autoprotocol.org
License¶
Copyright (c) 2017, Transcriptic Inc All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of autoprotocol-python nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TRANSCRIPTIC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Installation¶
$ git clone https://github.com/autoprotocol/autoprotocol-utilities
$ cd autoprotocol-utilities
$ python setup.py install
or
$ pip install autoprotocol_utilities
Contributing¶
The easiest way to contribute is to fork this repository and submit a pull request. You can also write an email to us if you want to discuss ideas or bugs.
- Vanessa Biggers: vanessa@transcriptic.com
- Cornelia Scheitz: cornelia.scheitz@gmail.com
autoprotocol-utilities is BSD licensed (see License). Before we can accept your pull request, we require that you sign a CLA (Contributor License Agreement) allowing us to distribute your work under the BSD license. Email one of the authors listed above for more details.
Source Code: https://github.com/autoprotocol/autoprotocol-utilities