Container Helper Functions

volume_check

autoprotocol_utilities.container_helpers.volume_check(well, usage_volume=0, use_safe_vol=False, use_safe_dead_diff=False)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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])

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)

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)

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