splitting mixes

[dave-doty]

Sometimes one wants to make a single large mix and split it across several test tubes. Have a way to specify this where one simply indicates the desired volumes/concentrations in each individual test tube, as well as the number of them (and possibly their names), and it should automatically figure out the volumes to mix in the large Mix, and print instructions for that and for splitting/aliquotting into several individual test tubes.

It should also support having a small excess (say default of 5% extra) in case there are a large number of test tubes, so that the final one does not suffer from the volume being significantly lower due to pipetting error on the other aliquots.

[dave-doty]

Release notes

We have added the function split_mix to the module mixes. It lets one create several identical "small" mixes (which in most use cases will later be differentiated by adding different things to them) by specifying what volumes/concentrations are desired in the individual small mixes, but then returns a Mix object for creating them the easy way: by creating one "large" Mix from which the small mixes will be aliquoted.

The advantages of this, compared to manually creating the larger mix:

1. One usually thinks in terms of the volumes desired in the smaller test tubes, not the larger mix.
2. When there are a large number of aliquots from the large mix, pipetting errors can add up and result in the final aliquot having insufficient volume. Therefore sometimes one wants the large mix to contain a slight excess of what is needed. This is handled by the parameter excess.

Usage:

from alhambra_mixes import Mix, FixedConcentration, FixedVolume, Strand, split_mix

# create mix of staples to be used in downstream mix
staples = [Strand(f'stap{i}', concentration='1uM') for i in range(10)]
staple_mix = Mix(
    actions = [FixedConcentration(components=staples, fixed_concentration='100 nM')],
    name='staple mix',
)

# describe other components in mix
m13 = Strand('m13 100nM', concentration='100nM')
buffer_10x = Component(name='10x buffer', concentration='100 mM')

# describe single mix desired for each individual "small" test tube
mix = Mix(
    actions=[
        FixedVolume(components=[buffer_10x], fixed_volume=f'10 uL'),
        FixedConcentration(components=[m13], fixed_concentration=f'1 nM'),
        FixedConcentration(components=[staple_mix], fixed_concentration=f'10 nM'),
    ],
    name='master mix',
    fixed_total_volume=f"100 uL",
)

# call split_mix to create "large" mix from which smaller mixes can be aliquoted
sm = split_mix(mix=mix, num_tubes=5, excess=0.1)
print(sm.instructions())

This should print the following:

## Mix "master mix":

| Component   | [Src]     | [Dest]     | #   | Ea Tx Vol   | Tot Tx Vol   | Location   | Note   |
|:------------|:----------|:-----------|:----|:------------|:-------------|:-----------|:-------|
| 10x buffer  | 100.00 mM | 10.00 mM   |     | 55.00 µl    | 55.00 µl     |            |        |
| m13 100nM   | 100.00 nM | 1.00 nM    |     | 5.50 µl     | 5.50 µl      |            |        |
| staple mix  | 100.00 nM | 10.00 nM   |     | 55.00 µl    | 55.00 µl     |            |        |
| Buffer      |           |            |     | 434.50 µl   | 434.50 µl    |            |        |
| *Total:*    |           | *10.00 mM* | *4* |             | *550.00 µl*  |            |        |

Aliquot 100 µl from this mix into 5 different test tubes.

Note that we require 500 µL total, but because excess was 0.1 (10%), we have 550 µL total, to guarantee that even with pipetting error on the first 4 aliquots, there will still be more than 100 µL remaining for the 5th aliquot.

The full function API (as of this writing) is

A "split mix" is a Mix that involves creating a large volume mix and splitting it into several
test tubes with identical contents. The advantage of specifying a split mix is that one can give
the desired volumes/concentrations in the individual test tubes (post splitting) and the number of
test tubes, and the correct amounts in the larger mix will automatically be calculated.

The Mix.instructions method of a split mix includes the additional instruction at the end
to aliquot from the larger mix.

Parameters

mix: The :any:Mix object describing what each individual smaller test tube should contain after the split.

num_tubes: The number of test tubes into which to split the large mix.

excess: A fraction (between 0 and 1) indicating how much extra of the large mix to make. This is useful when num_tubes is large, since the aliquots prior to the last test tube may take a small amount of extra volume, resulting in the final test tube receiving significantly less volume if the large mix contained only just enough total volume.

For example, if the total volume is 100 uL and num_tubes is 20, then each aliquot from the large mix to test tubes would be 100/20 = 5 uL. But if due to pipetting imprecision 5.05 uL is actually taken, then the first 19 aliquots will total to 195.05 = 95.95 uL, so there will only be 100 - 95.95 = 4.05 uL left for the last test tube. But by setting excess to 0.05, then to make 20 test tubes of 5 uL each, we would have 520*1.05 = 105 uL total, and in this case even assuming pipetting error resulting in taking 95.95 uL for the first 19 samples, there is still 105 - 95.95 = 9.05 uL left, more than enough for the 20'th test tube.

Note: using excess > 0 means than the test tube with the large mix should not be reused as one of the final test tubes, since it will have too much volume at the end.

Returns: A "large" mix, from which num_tubes aliquots can be made to create each of the identical "small" mixes.