autoprotocol.container

container.Container

class autoprotocol.container.Container(id, container_type, name=None, storage=None, cover=None)[source]

A reference to a specific physical container (e.g. a tube or 96-well microplate).

Every Container has an associated ContainerType, which defines the well count and arrangement, amongst other properties.

There are several methods on Container which present a convenient interface for defining subsets of wells on which to operate. These methods return a WellGroup.

Containers are usually declared using the Protocol.ref method.

Parameters
  • id (str, optional) – Alphanumerical identifier for a Container.

  • container_type (ContainerType) – ContainerType associated with a Container.

  • name (str, optional) – name of the container/ref being created.

  • storage (str, optional) – name of the storage condition.

  • cover (str, optional) – name of the cover on the container.

Raises

AttributeError – Invalid cover-type given

well(i)[source]

Return a Well object representing the well at the index specified of this Container.

Parameters

i (int, str) – Well reference in the form of an integer (ex: 0) or human-readable string (ex: “A1”).

Returns

Well for given reference

Return type

Well

Raises

TypeError – index given is not of the right type

well_from_coordinates(row, column)[source]

Gets the well at 0-indexed position (row, column) within the container. The origin is in the top left corner.

Parameters
  • row (int) – The 0-indexed row index of the well to be fetched

  • column (int) – The 0-indexed column index of the well to be fetched

Returns

The well at position (row, column)

Return type

Well

tube()[source]

Checks if container is tube and returns a Well representing the zeroth well.

Returns

Zeroth well of tube

Return type

Well

Raises

AttributeError – If container is not tube

wells(*args)[source]

Return a WellGroup containing references to wells corresponding to the index or indices given.

Parameters

args (str, int, list) – Reference or list of references to a well index either as an integer or a string.

Returns

Wells from specified references

Return type

WellGroup

Raises

TypeError – Well reference is not of a valid input type

robotize(well_ref)[source]

Return the integer representation of the well index given, based on the ContainerType of the Container.

Uses the robotize function from the ContainerType class. Refer to ContainerType.robotize() for more information.

humanize(well_ref)[source]

Return the human readable representation of the integer well index given based on the ContainerType of the Container.

Uses the humanize function from the ContainerType class. Refer to ContainerType.humanize() for more information.

decompose(well_ref)[source]

Return a tuple representing the column and row number of the well index given based on the ContainerType of the Container.

Uses the decompose function from the ContainerType class. Refer to ContainerType.decompose() for more information.

all_wells(columnwise=False)[source]

Return a WellGroup representing all Wells belonging to this Container.

Parameters

columnwise (bool, optional) – returns the WellGroup columnwise instead of rowwise (ordered by well index).

Returns

WellGroup of all Wells in Container

Return type

WellGroup

inner_wells(columnwise=False)[source]

Return a WellGroup of all wells on a plate excluding wells in the top and bottom rows and in the first and last columns.

Parameters

columnwise (bool, optional) – returns the WellGroup columnwise instead of rowwise (ordered by well index).

Returns

WellGroup of inner wells

Return type

WellGroup

wells_from(start, num, columnwise=False)[source]

Return a WellGroup of Wells belonging to this Container starting from the index indicated (in integer or string form) and including the number of proceeding wells specified. Wells are counted from the starting well rowwise unless columnwise is True.

Parameters
  • start (Well or int or str) – Starting well specified as a Well object, a human-readable well index or an integer well index.

  • num (int) – Number of wells to include in the Wellgroup.

  • columnwise (bool, optional) – Specifies whether the wells included should be counted columnwise instead of the default rowwise.

Returns

WellGroup of selected wells

Return type

WellGroup

Raises

TypeError – Incorrect input types, e.g. num has to be of type int

is_sealed()[source]

Check if Container is sealed.

is_covered()[source]

Check if Container is covered.

quadrant(quad)[source]

Return a WellGroup of Wells corresponding to the selected quadrant of this Container.

Parameters

quad (int or str) – Specifies the quadrant number of the well (ex. 2)

Returns

WellGroup of wells for the specified quadrant

Return type

WellGroup

Raises

ValueError – Invalid quadrant specified for this Container type

set_storage(storage)[source]

Set the storage condition of a container, will overwrite an existing storage condition, will remove discard True.

Parameters

storage (str) – Storage condition.

Returns

Container with modified storage condition

Return type

Container

Raises

TypeError – If storage condition not of type str.

discard()[source]

Set the storage condition of a container to None and container to be discarded if ref in protocol.

Example

p = Protocol()
container = p.ref("new_container", cont_type="96-pcr",
                  storage="cold_20")
p.incubate(c, "warm_37", "30:minute")
container.discard()

Autoprotocol generated:

.. code-block:: json

   "refs": {
      "new_container": {
        "new": "96-pcr",
        "discard": true
      }
    }
wells_from_shape(origin, shape)[source]

Gets a WellGroup that originates from the origin and is distributed across the container in shape. This group has a Well for each index in range(shape[“rows”] * shape[“columns”]).

In cases where the container dimensions are smaller than the shape format’s dimensions the returned WellGroup will reference some wells multiple times. This is analogous to an SBS96-formatted liquid handler acting with multiple tips in each well of an SBS24-formatted plate.

Parameters
  • origin (int or str) – The index of the top left corner origin of the shape

  • shape (dict) – See Also Instruction.builders.shape

Returns

The group of wells distributed in shape from the origin

Return type

WellGroup

Raises

ValueError – if the shape exceeds the extents of the container

__repr__()[source]

Return a string representation of a Container using the specified name. (ex. Container(‘my_plate’))

container.Well

class autoprotocol.container.Well(container, index)[source]

A Well object describes a single location within a container.

Do not construct a Well directly – retrieve it from the related Container object.

Parameters
  • container (Container) – The Container this well belongs to.

  • index (int) – The index of this well within the container.

set_properties(properties)[source]

Set properties for a Well. Existing property dictionary will be completely overwritten with the new dictionary.

Parameters

properties (dict) – Custom properties for a Well in dictionary form.

Returns

Well with modified properties

Return type

Well

add_properties(properties)[source]

Add properties to the properties attribute of a Well.

If any property with the same key already exists for the Well then:
  • if both old and new properties are lists then append the new property

  • otherwise overwrite the old property with the new one

Parameters

properties (dict) – Dictionary of properties to add to a Well.

Returns

Well with modified properties

Return type

Well

set_volume(vol)[source]

Set the theoretical volume of liquid in a Well.

Parameters

vol (str, Unit) – Theoretical volume to indicate for a Well.

Returns

Well with modified volume

Return type

Well

Raises
  • TypeError – Incorrect input-type given

  • ValueError – Volume set exceeds maximum well volume

set_name(name)[source]

Set a name for this well for it to be included in a protocol’s “outs” section

Parameters

name (str) – Well name.

Returns

Well with modified name

Return type

Well

humanize()[source]

Return the human readable representation of the integer well index given based on the ContainerType of the Well.

Uses the humanize function from the ContainerType class. Refer to ContainerType.humanize() for more information.

Returns

Index of well in Container (in human readable form)

Return type

str

available_volume()[source]

Returns the available volume of a Well. This is calculated as nominal volume - container_type dead volume

Returns

Volume in well

Return type

Unit(volume)

Raises

RuntimeError – Well has no volume

__repr__()[source]

Return a string representation of a Well.

container.WellGroup

class autoprotocol.container.WellGroup(wells)[source]

A logical grouping of Wells.

Wells in a WellGroup do not necessarily need to be in the same container.

Parameters

wells (list) – List of Well objects contained in this WellGroup.

Raises

TypeError – Wells is not of the right input type

set_properties(properties)[source]

Set the same properties for each Well in a WellGroup.

Parameters

properties (dict) – Dictionary of properties to set on Well(s).

Returns

WellGroup with modified properties

Return type

WellGroup

add_properties(properties)[source]

Add the same properties for each Well in a WellGroup.

Parameters

properties (dict) – Dictionary of properties to set on Well(s).

Returns

WellGroup with modified properties

Return type

WellGroup

set_volume(vol)[source]

Set the volume of every well in the group to vol.

Parameters

vol (Unit, str) – Theoretical volume of each well in the WellGroup.

Returns

WellGroup with modified volume

Return type

WellGroup

indices()[source]

Return the indices of the wells in the group in human-readable form, given that all of the wells belong to the same container.

Returns

List of humanized indices from this WellGroup

Return type

list(str)

append(other)[source]

Append another well to this WellGroup.

Parameters

other (Well) – Well to append to this WellGroup.

Returns

WellGroup with appended well

Return type

WellGroup

Raises

TypeError – other is not of type Well

extend(other)[source]

Extend this WellGroup with another WellGroup.

Parameters

other (WellGroup or list of Wells) – WellGroup to extend this WellGroup.

Returns

WellGroup extended with specified WellGroup

Return type

WellGroup

Raises

TypeError – Input WellGroup is not of the right type

set_group_name(name)[source]

Assigns a name to a WellGroup.

Parameters

name (str) – WellGroup name

Returns

Name of wellgroup

Return type

str

wells_with(prop, val=None)[source]

Returns a wellgroup of wells with the specified property and value

Parameters
  • prop (str) – the property you are searching for

  • val (str, optional) – the value assigned to the property

Returns

WellGroup with modified properties

Return type

WellGroup

Raises

TypeError – property or value defined does not have right input type

pop(index=-1)[source]

Removes and returns the last well in the wellgroup, unless an index is specified. If index is specified, the well at that index is removed from the wellgroup and returned.

Parameters

index (int, optional) – the index of the well you want to remove and return

Returns

Well with selected index from WellGroup

Return type

Well

insert(i, well)[source]

Insert a well at a given position.

Parameters
  • i (int) – index to insert the well at

  • well (Well) – insert this well at the index

Returns

WellGroup with inserted wells

Return type

WellGroup

Raises

TypeError – index or well defined does not have right input type

__setitem__(key, item)[source]

Set a specific Well in a WellGroup.

Parameters
  • key (int) – Position in a WellGroup in robotized form.

  • item (Well) – Well or WellGroup to be added

Raises

TypeError – Item specified is not of type Well

__getitem__(key)[source]

Return a specific Well from a WellGroup.

Parameters

key (int) – Position in a WellGroup in robotized form.

Returns

Specified well from given key

Return type

Well

__len__()[source]

Return the number of Wells in a WellGroup.

__repr__()[source]

Return a string representation of a WellGroup.

__add__(other)[source]

Append a Well or Wells from another WellGroup to this WellGroup.

Parameters

other (Well, WellGroup.) –

Returns

WellGroup with appended wells

Return type

WellGroup

Raises

TypeError – Input given is not of type Well or WellGroup