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