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 integer
  • ValueError – If base is not of type integer

printdatetime

autoprotocol_utilities.misc_helpers.printdatetime()[source]

Generate a datetime string.

Returns:The current date and time formatted as: YYYY-MM-DD_HH-MM-SS
Return type:str

printdate

autoprotocol_utilities.misc_helpers.printdate()[source]

Generate a date string.

Returns:The current date formatted as: YYYY-MM-DD
Return type:str

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

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 WellGroup
  • ValueError – 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 Well
  • ValueError – 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 float
  • RuntimeError – 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 WellGroup
  • ValueError – 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 WellGroup
  • ValueError – 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 WellGroup
  • ValueError – 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 WellGroup
  • ValueError – If elements of wells are not of type well
  • ValueError – 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 WellGroup
  • StopIteration – 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 Container
  • ValueError – 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 Container
  • ValueError – 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

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

2.0.1 2016-03-29

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

1.2.0 2016-02-22

1.1.0 2016-02-19

1.0.0 2016-02-18

  • [Feature]: Initial release

Credits

Autoprotocol-utilities is currently maintained by:

See all Github contributors

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.

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

Search the Docs

copyright:2017 by The Autoprotocol Development Team, see Credits for more details.
license:BSD, see License for more details