riverine.actions

riverine.actions#

Attributes#

`T`
`T_AWC`
`MultiFixedConcentration`
`MultiFixedVolume`

Classes#

`MixVolumeDep`	Create a collection of name/value pairs.
`AbstractAction`	Abstract class defining an action in a mix recipe.
`ActionWithComponents`	Abstract class defining an action in a mix recipe.
`FixedVolume`	An action adding one or multiple components, with a set transfer volume.
`EqualConcentration`	An action adding an equal concentration of each component, without setting that concentration.
`FixedConcentration`	An action adding one or multiple components, with a set destination concentration per component (adjusting volumes).
`ToConcentration`	Add an amount of (non-mix) components to result in a fixed total concentration of each in the mix.
`FillToVolume`	Abstract class defining an action in a mix recipe.

Module Contents#

class riverine.actions.MixVolumeDep(*args, **kwds)[source]#

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access:
```
>>> Color.RED
<Color.RED: 1>
```
value lookup:
```
>>> Color(1)
<Color.RED: 1>
```
name lookup:
```
>>> Color['RED']
<Color.RED: 1>
```

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

INDEPENDENT = 'independent'[source]#

DEPENDS = 'depends'[source]#

DETERMINES = 'determines'[source]#

riverine.actions.T[source]#

class riverine.actions.AbstractAction[source]#

Abstract class defining an action in a mix recipe.

property name: str[source]#

Abstractmethod:

abstractmethod mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

_get_name(_cache_key=None) → str[source]#

tx_volume(mix_vol: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → riverine.units.DecimalQuantity[source]#

The total volume transferred by the action to the sample. May depend on the total mix volume.

Parameters:: mix_vol – The mix volume. Does not accept strings.

abstractmethod _mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → riverine.units.Sequence[riverine.printing.MixLine][source]#

abstractmethod all_components(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → pandas.DataFrame[source]#

A dataframe containing all base components added by the action.

Parameters:: mix_vol – The mix volume. Does not accept strings.

abstractmethod with_experiment(experiment: riverine.experiments.Experiment, *, inplace: bool = True) → T[source]#: Returns a copy of the action updated from a experiment dataframe.

abstractmethod with_reference(reference: riverine.references.Reference, *, inplace: bool = False) → T[source]#: Returns a copy of the action updated from a reference dataframe.

dest_concentration(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), cache_key=None) → riverine.units.DecimalQuantity[source]#

The destination concentration added to the mix by the action.

Raises:: ValueError – There is no good definition for a single destination concentration (the action may add multiple components).

dest_concentrations(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), cache_key=None) → riverine.units.Sequence[riverine.units.DecimalQuantity][source]#

property components: list[riverine.components.AbstractComponent][source]#

Abstractmethod:

property source_concentrations: list[riverine.units.DecimalQuantity][source]#

abstractmethod _get_source_concentrations(_cache_key=None) → list[riverine.units.DecimalQuantity][source]#

abstractmethod each_volumes(mix_volume: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

classmethod _structure(d: dict[str, Any], experiment: riverine.experiments.Experiment) → AbstractAction[source]#

Abstractmethod:

abstractmethod _unstructure(experiment: riverine.experiments.Experiment | None) → dict[str, Any][source]#

riverine.actions.T_AWC[source]#

class riverine.actions.ActionWithComponents[source]#

Bases: AbstractAction

Abstract class defining an action in a mix recipe.

__hash__[source]#

components: list[riverine.components.AbstractComponent | str][source]#

property number: int[source]#

_get_number(_cache_key=None) → int[source]#

property name: str[source]#

abstractmethod mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

__eq__(other: object) → bool[source]#

with_experiment(experiment: riverine.experiments.Experiment, *, inplace: bool = True) → T_AWC[source]#: Returns a copy of the action updated from a experiment dataframe.

with_reference(reference: riverine.references.Reference, *, inplace: bool = False) → T_AWC[source]#: Returns a copy of the action updated from a reference dataframe.

property source_concentrations: list[riverine.units.DecimalQuantity][source]#

_get_source_concentrations(_cache_key=None) → list[riverine.units.DecimalQuantity][source]#

_unstructure(experiment: riverine.experiments.Experiment | None) → dict[str, Any][source]#

classmethod _structure(d: dict[str, Any], experiment: riverine.experiments.Experiment | None = None) → ActionWithComponents[source]#

all_components_polars(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → pandas.DataFrame[source]#

all_components(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = ()) → pandas.DataFrame[source]#

A dataframe containing all base components added by the action.

Parameters:: mix_vol – The mix volume. Does not accept strings.

_compactstrs(tablefmt: str | riverine.printing.TableFormat, dconcs: riverine.units.Sequence[riverine.units.DecimalQuantity], eavols: riverine.units.Sequence[riverine.units.DecimalQuantity]) → riverine.units.Sequence[riverine.printing.MixLine][source]#

class riverine.actions.FixedVolume[source]#

Bases: ActionWithComponents

An action adding one or multiple components, with a set transfer volume.

Parameters:

components – A list of Components.
fixed_volume – A fixed volume for the action. Input can be a string (eg, “5 µL”) or a pint Quantity. The interpretation of this depends on equal_conc.
set_name – The name of the mix. If not set, name is based on components.
compact_display – If True (default), the action tries to display compactly in mix recipes. If False, it displays each component as a separate line.

Examples

>>> from riverine.mixes import *
>>> components = [
...     Component("c1", "200 nM"),
...     Component("c2", "200 nM"),
...     Component("c3", "200 nM"),
... ]

>>> print(Mix([FixedVolume(components, "5 uL")], name="example"))
Table: Mix: example, Conc: 66.67 nM, Total Vol: 15.00 µl

| Comp       | Src []    | Dest []   |   # | Ea Tx Vol   | Tot Tx Vol   | Loc   | Note   |
|:-----------|:----------|:----------|----:|:------------|:-------------|:------|:-------|
| c1, c2, c3 | 200.00 nM | 66.67 nM  |   3 | 5.00 µl     | 15.00 µl     |       |        |

fixed_volume: riverine.units.DecimalQuantity[source]#

set_name: str | None = None[source]#

compact_display: bool = True[source]#

dest_concentrations(mix_vol: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

each_volumes(mix_volume: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

property name: str[source]#

_get_name(_cache_key=None) → str[source]#

_mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.printing.MixLine][source]#

mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

class riverine.actions.EqualConcentration(components: riverine.units.Sequence[riverine.components.AbstractComponent | str] | riverine.components.AbstractComponent | str, fixed_volume: str | riverine.units.DecimalQuantity, set_name: str | None = None, compact_display: bool = True, method: Literal['max_volume', 'min_volume', 'check'] | tuple[Literal['max_fill'], str] = 'min_volume', equal_conc: bool | str | None = None)[source]#

Bases: FixedVolume

An action adding an equal concentration of each component, without setting that concentration.

Depending on the setting of equal_conc, it may require that the concentrations all be equal to begin with, or may treat the fixed transfer volume as the volume as the minimum or maximum volume to transfer, adjusting volumes of each strand to make this work and have them at equal destination concentrations.

Parameters:

components – A list of Components.
fixed_volume – A fixed volume for the action. Input can be a string (eg, “5 µL”) or a pint Quantity. The interpretation of this depends on equal_conc.
set_name – The name of the mix. If not set, name is based on components.
compact_display – If True (default), the action tries to display compactly in mix recipes. If False, it displays each component as a separate line.
method – If “check”, the action still transfers the same volume of each component, but will raise a ValueError if this will not result in every component having the same concentration added (ie, if they have different source concentrations). If “min_volume”, the action will transfer at least fixed_volume of each component, but will transfer more for components with lower source concentration, so that the destination concentrations are all equal (but not fixed to a specific value). If “max_volume”, the action instead transfers at most fixed_volume of each component, tranferring less for higher source concentration components. If (‘max_fill’, buffer_name), the fixed volume is the maximum, while for every component that is added at a lower volume, a corresponding volume of buffer is added to bring the total volume of the two up to the fixed volume.
[ (>>> components =)
Component("c1" (...)
nM") ("200)

:param : :param … Component(“c2”: :param “200 nM”): :param : :param … Component(“c3”: :param “200 nM”): :param : :param … Component(“c4”: :param “100 nM”): :param … ]: :param >>> print(Mix([EqualConcentration(components: :param “5 uL”: :param method=”min_volume”)]: :param name=”example”)): :param Table: :type Table: Mix: example, Conc: 40.00 nM, Total Vol: 25.00 µl :param <BLANKLINE>: :param | Comp | Src [] | Dest [] | # | Ea Tx Vol | Tot Tx Vol | Loc | Note |: :param |: :type |: -----------|:———-|:----------|:—-|:------------|:————-|:------|:——-| :param | c1: :param c2: :param c3 | 200.00 nM | 40.00 nM | 3 | 5.00 µl | 15.00 µl | | |: :param | c4 | 100.00 nM | 40.00 nM | 1 | 10.00 µl | 10.00 µl | | |: :param >>> print(Mix([EqualConcentration(components: :param "5 uL": :param method="max_volume")]: :param name="example")): :param Table: :type Table: Mix: example, Conc: 40.00 nM, Total Vol: 12.50 µl :param <BLANKLINE>: :param | Comp | Src [] | Dest [] | # | Ea Tx Vol | Tot Tx Vol | Loc | Note |: :param |: :type |: -----------|:———-|:----------|:—-|:------------|:————-|:------|:——-| :param | c1: :param c2: :param c3 | 200.00 nM | 40.00 nM | 3 | 2.50 µl | 7.50 µl | | |: :param | c4 | 100.00 nM | 40.00 nM | 1 | 5.00 µl | 5.00 µl | | |:

__hash__[source]#

method: Literal['max_volume', 'min_volume', 'check'] | tuple[Literal['max_fill'], str] = 'min_volume'[source]#

property source_concentrations: list[riverine.units.DecimalQuantity][source]#

_get_source_concentrations(_cache_key=None) → list[riverine.units.DecimalQuantity][source]#

each_volumes(mix_volume: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

tx_volume(mix_vol: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → riverine.units.DecimalQuantity[source]#

The total volume transferred by the action to the sample. May depend on the total mix volume.

Parameters:: mix_vol – The mix volume. Does not accept strings.

_mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.printing.MixLine][source]#

mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

class riverine.actions.FixedConcentration[source]#

Bases: ActionWithComponents

An action adding one or multiple components, with a set destination concentration per component (adjusting volumes).

FixedConcentration adds a selection of components, with a specified destination concentration.

Parameters:

components – A list of Components.
fixed_concentration – A fixed concentration for the action. Input can be a string (eg, “50 nM”) or a pint Quantity.
set_name – The name of the mix. If not set, name is based on components.
compact_display – If True (default), the action tries to display compactly in mix recipes. If False, it displays each component as a separate line.
min_volume – Specifies a minimum volume that must be transferred per component. Currently, this is for validation only: it will cause a VolumeError to be raised if a volume is too low.

Raises:

VolumeError – One of the volumes to transfer is less than the specified min_volume.

Examples

>>> from riverine.mixes import *
>>> components = [
...     Component("c1", "200 nM"),
...     Component("c2", "200 nM"),
...     Component("c3", "200 nM"),
...     Component("c4", "100 nM")
... ]

>>> print(Mix([FixedConcentration(components, "20 nM")], name="example", fixed_total_volume="25 uL"))
Table: Mix: example, Conc: 40.00 nM, Total Vol: 25.00 µl

| Comp       | Src []    | Dest []   | #   | Ea Tx Vol   | Tot Tx Vol   | Loc   | Note   |
|:-----------|:----------|:----------|:----|:------------|:-------------|:------|:-------|
| c1, c2, c3 | 200.00 nM | 20.00 nM  | 3   | 2.50 µl     | 7.50 µl      |       |        |
| c4         | 100.00 nM | 20.00 nM  |     | 5.00 µl     | 5.00 µl      |       |        |
| Buffer     |           |           |     |             | 12.50 µl     |       |        |
| *Total:*   |           | 40.00 nM  |     |             | 25.00 µl     |       |        |

fixed_concentration: riverine.units.DecimalQuantity[source]#

set_name: str | None = None[source]#

compact_display: bool = True[source]#

min_volume: riverine.units.DecimalQuantity[source]#

dest_concentrations(mix_vol: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

each_volumes(mix_volume: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

_mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.printing.MixLine][source]#

property name: str[source]#

mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

class riverine.actions.ToConcentration[source]#

Bases: ActionWithComponents

Add an amount of (non-mix) components to result in a fixed total concentration of each in the mix.

An action adding an amount of components such that the concentration of each component in the mix will be at some target concentration. Unlike FixedConcentration, which adds a certain concentration, this takes into account other contents of the mix, and only adds enough to reach a particular final concentration.

fixed_concentration: riverine.units.DecimalQuantity[source]#

compact_display: bool = True[source]#

min_volume: riverine.units.DecimalQuantity[source]#

_othercomps(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None)[source]#

dest_concentrations(mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → riverine.units.Sequence[riverine.units.DecimalQuantity][source]#

each_volumes(mix_volume: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

_mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.printing.MixLine][source]#

mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.

riverine.actions.MultiFixedConcentration[source]#

riverine.actions.MultiFixedVolume[source]#

class riverine.actions.FillToVolume[source]#

Bases: ActionWithComponents

Abstract class defining an action in a mix recipe.

target_total_volume: riverine.units.DecimalQuantity[source]#

dest_concentrations(mix_vol: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

each_volumes(mix_volume: riverine.units.DecimalQuantity = NAN_VOL, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.units.DecimalQuantity][source]#

_mixlines(tablefmt: str | riverine.printing.TableFormat, mix_vol: riverine.units.DecimalQuantity, actions: riverine.units.Sequence[AbstractAction] = (), _cache_key=None) → list[riverine.printing.MixLine][source]#

mix_volume_effect(_cache_key=None)[source]#

The effect of the action on the mix volume.

Returns:

MixVolumeDep – How the mix volume affects the action.
DecimalQuantity – If MixVolumeDep is DETERMINES, the total mix volume that the action causes. If MixVolumeDep is DEPENDS, NAN. If MixVolumeDep is INDEPENDENT, the total volume that the action adds.