autoprotocol.container¶

container.Container¶

class autoprotocol.container.Container(id: Optional[str] = None, container_type: Union[autoprotocol.container_type.ContainerType, str] = '', name: Optional[str] = None, storage: Optional[str] = None, cover: Optional[str] = None, properties: Optional[dict] = None, ctx_properties: Optional[dict] = 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.
properties (dict, optional) – mapping of key value properties associated to the Container
ctx_properties (dict, optional) – mapping of key value properties associated to the Container

Raises

AttributeError – Invalid cover-type given

well(i) → autoprotocol.container.Well[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: autoprotocol.container.Container, index: int, volume: Optional[Union[str, autoprotocol.unit.Unit]] = None, mass: Optional[Union[str, autoprotocol.unit.Unit]] = None, name: Optional[str] = None, compounds: Optional[list] = None, properties: Optional[dict] = None, ctx_properties: Optional[dict] = None)[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.
properties (dict, optional) – mapping of key value properties associated to the Container
ctx_properties (dict, optional) – mapping of key value properties associated to the Container

set_mass(mass)[source]¶

Set the theoretical mass of contents in a Well.

Parameters: mass (str, Unit) – Theoretical mass to indicate for a Well.
Returns: Well with modified mass
Return type: Well
Raises: TypeError – Incorrect input-type given

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_compounds(compounds)[source]¶

Sets the list of associated compounds, and their metadata, to an aliquot.

Parameters: compounds (list) – List of compounds associated to a well.
Returns: Well with associated compounds
Return type: Well
Raises: TypeError – Incorrect input-type given

add_volume(vol: autoprotocol.unit.Unit)[source]¶

Updates the volume of the well

Parameters

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

Returns

the updated volume of the Well

Return type

Unit

Raises

TypeError – Error when input does not match expected type or dimensionality
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