Pipette transfer

[andySigler]

This PR adds a commands Pipette.transfer(), Pipette.distribute(), and Pipette.consolidate():

(see autoprotocol for inspiration)

# one to one
pipette.transfer(30, plate['A1'], plate['B2'])

# many to many (lists must be same length)
pipette.transfer(30, plate.rows['1'], plate.rows['2'])

# one to many
pipette.distribute(30, trough['A1'], plate)

# many to one
pipette.consolidate(30, plate, trough['A1'])

# dispense with a multi-channel to all rows
multi_channel.distribute(50, trough['A1'], plate.rows)

# dispense with a multi-channel to all even rows
multi_channel.distribute(50, trough['A1'], plate.rows[::2])

# automatically handle volumes larger than the pipette
# by breaking it up into separate aspirate/dispenses (called `carryover`)
pipette.transfer(2000, plate['A1'], plate['A2'])

# if you don't want this, and instead want the API to raise an error
# if volume is too long, you can say `carryover=False`
pipette.transfer(2000, plate['A1'], plate('A2'), carryover=False)  # raises error

# distributes will combine aspirates together by default
p200.distribute(50, plate['A1'], plate.rows['2'])
# -> pick up new tip
# -> aspirate 200uL at plate:A1
# -> dispense 50uL at plate:A2
# -> dispense 50uL at plate:B2
# -> dispense 50uL at plate:C2
# -> dispense 50uL at plate:D2
# -> aspirate 200uL at plate:A1
# -> dispense 50uL at plate:E2
# -> dispense 50uL at plate:F2
# -> dispense 50uL at plate:G2
# -> dispense 50uL at plate:H2
# -> return tip

# if you want every aspirate volume to be separate
# you can set `repeat=False`
p200.distribute(50, plate['A1'], plate.rows['2'], repeat=False)
# -> pick up new tip
# -> aspirate 50uL at plate:A1
# -> dispense 50uL at plate:A2
# -> aspirate 50uL at plate:A1
# -> dispense 50uL at plate:B2
.... etc
# -> return tip

# specify number of tips to be used
pipette.transfer(30, plate['A1'], plate['A2'], new_tip='once')  # default behavior, no need to specify tips=1

# if you need to use the tip either before or after the command, say tips=0 and 
pipette.pick_up_tip().mix(plate['A1'])
pipette.transfer(30, plate['A1'], plate['A2'], new_tip='never')
pipette.aspirate(10, plate['A2']).drop_tip()

# change tip after each and every dispense
pipette.transfer(30, plate_1, plate_2, new_tip='every')

# if volume is a tuple, creates a linear gradient of volumes
pipette.transfer((10, 40), trough['A1'], plate[:4])
# -> A1 = 10
# -> B1 = 20
# -> C1 = 30
# -> D1 = 40

# option to set custom gradient function
pipette.transfer((10, 40), trough['A1'], plate[:8],
                 gradient=lambda x:  math.sin(x * math.pi))
# -> A1 = 10.00
# -> B1 = 23.02
# -> C1 = 33.46
# -> D1 = 39.25
# -> E1 = 39.25
# -> F1 = 33.46
# -> G1 = 23.02
# -> H1 = 10.00

The commands take a series of optional kew-word arguments, the defaults are shown below:

pipette.transfer(
    volume,               # number or list or tuple
    sources,              # Placeable or list (length must match targets)
    targets,              # Placeable or list (length must match sources)
    trash=True,          # send tips to trash
    touch_tip=False,          # after each aspirate and dispense
    blow_out=False,           # after a dispense (if tip is empty)
    mix_before=(0, 0),    # before each aspirate 
    mix_after=(0, 0),     # after each dispense 
    new_tip='once',          # defaults to 'once', can also be 'never' or 'always'
    carryover=True,       # split transfers if volumes are too high
    gradient=lambda x: x  # x is target's position in list, range 0.0-1.0
)

pipette.distribute(
    volume,
    source,               # Placeable
    targets,              # list
    trash=True,
    touch_tip=False,
    blow_out=False,
    mix_before=(0, 0),
    tips=1,
    carryover=True,
    repeat=True,          # compress sequential distribute volumes into single aspirate
    gradient=lambda x: x
)

pipette.consolidate(
    volume,
    sources,              # list
    target,               # Placeable
    trash=True,
    touch_tip=False,
    blow_out=False,
    mix_after=(0, 0),
    tips=1,
    carryover=True,
    repeat=True,          # compress sequential aspirate volumes into single dispense
    gradient=lambda x: x
)

[coveralls]

Coverage decreased (-0.01%) to 94.78% when pulling e299c3e on pipette-transfer into 7dfff76 on master.

[coveralls]

Coverage increased (+0.1%) to 94.888% when pulling 994b923 on pipette-transfer into 7dfff76 on master.

[coveralls]

Coverage increased (+0.2%) to 95.448% when pulling a13450c on pipette-transfer into cb73fa3 on master.

[coveralls]

Coverage increased (+0.1%) to 95.421% when pulling b29e288 on pipette-transfer into f17d0ec on master.

[coveralls]

Coverage increased (+0.2%) to 95.518% when pulling 7ffa24a on pipette-transfer into f17d0ec on master.

[coveralls]

Coverage increased (+0.3%) to 95.542% when pulling 846e236 on pipette-transfer into f17d0ec on master.

[coveralls]

Coverage increased (+0.2%) to 95.501% when pulling 1365dca on pipette-transfer into f17d0ec on master.

[coveralls]

Coverage increased (+0.3%) to 95.787% when pulling 38e782a on pipette-transfer into 91e25ae on master.

[coveralls]

Coverage increased (+0.4%) to 95.865% when pulling e5e512a on pipette-transfer into 2d3e638 on master.

[coveralls]

Coverage increased (+0.4%) to 95.865% when pulling 9815092 on pipette-transfer into 2d3e638 on master.

[coveralls]

Coverage increased (+0.4%) to 95.885% when pulling e252685 on pipette-transfer into 2d3e638 on master.

[coveralls]

Coverage increased (+0.4%) to 95.868% when pulling 5fb8c13 on pipette-transfer into 2d3e638 on master.

[coveralls]

Coverage increased (+0.4%) to 95.896% when pulling 15846ef on pipette-transfer into 2d3e638 on master.

[coveralls]

Coverage increased (+0.3%) to 95.757% when pulling 9453e12 on pipette-transfer into 2d3e638 on master.