opentrons_API_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/jgs286/.opentrons/deck_calibration.json not found. Loading defaults\n",
      "/Users/jgs286/.opentrons/robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Loading json containers...\n",
      "Json container file load complete, listing database\n",
      "Found 0 containers to add. Starting migration...\n",
      "Database migration complete!\n"
     ]
    }
   ],
   "source": [
    "from opentrons import protocol_api\n",
    "from opentrons import simulate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# New Protocol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Metadata declaration\n",
    "\n",
    "You must declare the protocol API version and author."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "metadata = {\n",
    "    'apiLevel': 2.2,\n",
    "    'author': 'Jon Sanders'}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Declare a protocol"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "from opentrons.protocols.types import APIVersion"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "api_version = APIVersion(2, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/jgs286/.opentrons/deck_calibration.json not found. Loading defaults\n",
      "/Users/jgs286/.opentrons/robot_settings.json not found. Loading defaults\n"
     ]
    }
   ],
   "source": [
    "protocol = protocol_api.ProtocolContext(api_version=api_version)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<opentrons.protocol_api.protocol_context.ProtocolContext at 0x118d8f320>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "protocol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pipette setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we should specify tipracks associated with each pipette. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "tiprack_left_1 = protocol.load_labware('opentrons_96_filtertiprack_200ul', 1)\n",
    "tiprack_left_3 = protocol.load_labware('opentrons_96_filtertiprack_200ul', 3)\n",
    "tiprack_right = protocol.load_labware('opentrons_96_filtertiprack_10ul', 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we'll load pipettes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipette_left = protocol.load_instrument('p300_multi', \n",
    "                                        'left',\n",
    "                                        tip_racks=[tiprack_left_1,\n",
    "                                                   tiprack_left_3])\n",
    "\n",
    "pipette_right = protocol.load_instrument('p10_multi', \n",
    "                                        'right',\n",
    "                                        tip_racks=[tiprack_right])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can alter parameters of the pipette using its properties.\n",
    "\n",
    "#### Flow rate\n",
    "\n",
    "This changes the rate at which the pipette plungers moves, and is expressed in units of µL/s. \n",
    "\n",
    "We can access the `flowrate.aspirate` property of a loaded `InstrumentContext` object to change it:\n",
    "\n",
    "```\n",
    "pipette_left.flow_rate.aspirate = 50\n",
    "pipette_left.flow_rate.dispense = 200\n",
    "pipette_left.flow_rate.blow_out = 100\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Bottom clearance\n",
    "\n",
    "Bottom clearnce for aspirate and dispense actions can be set for a whole pipette to allow it to be set for repeated motions (like with the `pipette.transfer` command). By default both aspirate and dispense actions take place 1 mm above the bottom of the well. This is also set as a property of the `InstrumentContext` object:\n",
    "\n",
    "```\n",
    "pipette_right.well_bottom_clearance.aspirate = 0.5\n",
    "pipette_right.well_bottom_clearance.dispense = 2\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1.0"
      ]
     },
     "execution_count": 103,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_left.well_bottom_clearance.dispense\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading labware\n",
    "\n",
    "Labware is defined using the `protocol.load_labware` function. The generic signature is:\n",
    "\n",
    "```plate = protocol.load_labware(load_name, location, label)```\n",
    "\n",
    "`load_name` must be a `str` referring to an existing entry in the labware database; `location` can be an int or numeric string specifying a deck slot, and `label` is an optional parameter to give the labware a nickname.,\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "reagents = protocol.load_labware('nest_12_reservoir_15ml', 6, 'reagents')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "assay = protocol.load_labware('corning_96_wellplate_360ul_flat', 5, 'assay')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "samples = protocol.load_labware('biorad_96_wellplate_200ul_pcr', 4, 'samples')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Accessing wells"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "assay on 5"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A1 of assay on 5"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.columns()[0][0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "foo = assay.columns()[0][0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A1 of assay on 5\n",
      "A2 of assay on 5\n",
      "A3 of assay on 5\n",
      "A4 of assay on 5\n",
      "A5 of assay on 5\n",
      "A6 of assay on 5\n",
      "A7 of assay on 5\n",
      "A8 of assay on 5\n",
      "A9 of assay on 5\n",
      "A10 of assay on 5\n",
      "A11 of assay on 5\n",
      "A12 of assay on 5\n"
     ]
    }
   ],
   "source": [
    "for well in assay.rows()[0]:\n",
    "    print(well)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[A1 of assay on 5, A2 of assay on 5, A3 of assay on 5, A4 of assay on 5, A5 of assay on 5, A6 of assay on 5, A7 of assay on 5, A8 of assay on 5, A9 of assay on 5, A10 of assay on 5, A11 of assay on 5, A12 of assay on 5]\n",
      "[B1 of assay on 5, B2 of assay on 5, B3 of assay on 5, B4 of assay on 5, B5 of assay on 5, B6 of assay on 5, B7 of assay on 5, B8 of assay on 5, B9 of assay on 5, B10 of assay on 5, B11 of assay on 5, B12 of assay on 5]\n",
      "[C1 of assay on 5, C2 of assay on 5, C3 of assay on 5, C4 of assay on 5, C5 of assay on 5, C6 of assay on 5, C7 of assay on 5, C8 of assay on 5, C9 of assay on 5, C10 of assay on 5, C11 of assay on 5, C12 of assay on 5]\n",
      "[D1 of assay on 5, D2 of assay on 5, D3 of assay on 5, D4 of assay on 5, D5 of assay on 5, D6 of assay on 5, D7 of assay on 5, D8 of assay on 5, D9 of assay on 5, D10 of assay on 5, D11 of assay on 5, D12 of assay on 5]\n",
      "[E1 of assay on 5, E2 of assay on 5, E3 of assay on 5, E4 of assay on 5, E5 of assay on 5, E6 of assay on 5, E7 of assay on 5, E8 of assay on 5, E9 of assay on 5, E10 of assay on 5, E11 of assay on 5, E12 of assay on 5]\n",
      "[F1 of assay on 5, F2 of assay on 5, F3 of assay on 5, F4 of assay on 5, F5 of assay on 5, F6 of assay on 5, F7 of assay on 5, F8 of assay on 5, F9 of assay on 5, F10 of assay on 5, F11 of assay on 5, F12 of assay on 5]\n",
      "[G1 of assay on 5, G2 of assay on 5, G3 of assay on 5, G4 of assay on 5, G5 of assay on 5, G6 of assay on 5, G7 of assay on 5, G8 of assay on 5, G9 of assay on 5, G10 of assay on 5, G11 of assay on 5, G12 of assay on 5]\n",
      "[H1 of assay on 5, H2 of assay on 5, H3 of assay on 5, H4 of assay on 5, H5 of assay on 5, H6 of assay on 5, H7 of assay on 5, H8 of assay on 5, H9 of assay on 5, H10 of assay on 5, H11 of assay on 5, H12 of assay on 5]\n"
     ]
    }
   ],
   "source": [
    "for row in assay.rows():\n",
    "    print(row)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can access individual wells by name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "well_dict = assay.wells_by_name()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A11 of assay on 5"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "well_dict['A11']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A1 of assay on 5"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.wells_by_name()['A1']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A12 of assay on 5"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.wells_by_name()['A12']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This `dict` is also present as a key method of labware class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A1 of assay on 5"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay['A1']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Same with rows or cols:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[A1 of assay on 5,\n",
       " A2 of assay on 5,\n",
       " A3 of assay on 5,\n",
       " A4 of assay on 5,\n",
       " A5 of assay on 5,\n",
       " A6 of assay on 5,\n",
       " A7 of assay on 5,\n",
       " A8 of assay on 5,\n",
       " A9 of assay on 5,\n",
       " A10 of assay on 5,\n",
       " A11 of assay on 5,\n",
       " A12 of assay on 5]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.rows_by_name()['A']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And they can be accessed as zero-indexed lists, using col-ordering for plates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[A1 of assay on 5,\n",
       " B1 of assay on 5,\n",
       " C1 of assay on 5,\n",
       " D1 of assay on 5,\n",
       " E1 of assay on 5,\n",
       " F1 of assay on 5,\n",
       " G1 of assay on 5,\n",
       " H1 of assay on 5]"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.columns_by_name()['1']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "foo = assay.wells()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A1 of assay on 5"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.wells()[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "B1 of assay on 5"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.wells()[1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A2 of assay on 5"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay.wells()[8]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Positioning within wells"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `well` class returned in the above lists has class methods that pertain to their physical location in space relative to the instrument home. \n",
    "\n",
    "The is an object of class `Location`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Top\n",
    "\n",
    "The top center of the well physical well, necessarily above the liquid level. Also takes a `z` offset parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "A1 = assay.wells()[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=146.88, y=164.74, z=14.219999999999999), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.top()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=146.88, y=164.74, z=15.219999999999999), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.top(z=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Bottom\n",
    "\n",
    "The bottom center of the well. Also takes a Z offset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=146.88, y=164.74, z=3.549999999999999), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.bottom()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=146.88, y=164.74, z=4.549999999999999), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.bottom(z=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Center\n",
    "\n",
    "Vertical and horizontal center of well. Does *not* take a z offset. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=146.88, y=164.74, z=8.884999999999998), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.center()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instead, you can feed the `Location` class a `move` method, which takes a `Point` class that gives it a relative offset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "from opentrons import types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=145.88, y=165.74, z=7.884999999999998), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.center().move(types.Point(x=-1, y=1, z=-1))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=147.88, y=165.74, z=7.884999999999998), labware=A1 of assay on 5)"
      ]
     },
     "execution_count": 38,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A1.center().move(types.Point(1, 1, -1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hardware Modules"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [],
   "source": [
    "magblock = protocol.load_module('Magnetic Module', 11)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "MagneticModuleContext at Magnetic Module on 11 lw None"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "magblock"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'disengaged'"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "magblock.status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also load labware onto the module:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [],
   "source": [
    "mag_plate = magblock.load_labware('biorad_96_wellplate_200ul_pcr')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To engage the magnets, you can call the `engage` method, as long as the labware has a magnetic module behavior context defined:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [],
   "source": [
    "magblock.engage()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'engaged'"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "magblock.status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the labware is supported with the default `engage`, you can also specify an offset from default to tweak:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [],
   "source": [
    "magblock.disengage()\n",
    "magblock.engage(offset=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If it doesn't, then you can use `engage` with the `height_from_base` parameter to specify how many mm above the base of thye labware to put the tops of the magnets. There's a range of 1mm of variation in magnet position, though, so this might need to be a bit conservative."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [],
   "source": [
    "magblock.disengage()\n",
    "magblock.engage(height_from_base=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'engaged'"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "magblock.status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building block commands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Building block commands are the simplest individual commands of the API. `transfer` is a complex command, comprising basic commands like `pick_up_tip`, `aspirate`, `dispense`, and `drop_tip`. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before any motion commands are called, the 'instrument' must be homed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol.home()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Tip handling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tips can be picked up from a particular location within a tiprack:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p300_multi_v1 in LEFT>"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_left.pick_up_tip(tiprack_left.wells_by_name()['A1'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They can also be picked up automatically from the next available position:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.pick_up_tip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And then returned to their original location:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.return_tip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They can be also be dropped in a particular location, or if called to drop without specifying a location, will be discarded in the trash:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p300_multi_v1 in LEFT>"
      ]
     },
     "execution_count": 81,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_left.drop_tip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Liquid handling"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`aspirate` and `dispense` commands take volume, location, and rate arguments. `rate` species a multiple of the pipette's default, which is specified in the [labware definition](https://docs.opentrons.com/v2/new_pipette.html#defaults).\n",
    "\n",
    "By default, the aspirate and dispense commands both take place 1 mm above the bottom of the well. This can be changed by specifying an alternate location in the command, or by changing the protocol default with `InstrumentContext.well_bottom_clearance`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.pick_up_tip()\n",
    "\n",
    "pipette_right.aspirate(2, samples['A1'].bottom(z=2), rate=0.5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.dispense(2, assay['A1'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also `mix`, `blow_out`, and `touch_tip` basic commands to help with dealing with fluid properties.\n",
    "\n",
    "These commands happen at the current location by default, but specific locations can be specified."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 84,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# mix 5 times, with a 10 µL volume, 4 mm above the bottom of the well\n",
    "pipette_right.mix(5, 10, assay['A1'].bottom(z=4))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 85,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# blow out above the well\n",
    "pipette_right.blow_out(assay['A1'].top())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `touch_tip` command will by defualt touch each side of the well from the current location. You can specify a particular well, offset from the top, the radius of the touch, and the speed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 87,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# touch tips to each side of the well to knock of droplets\n",
    "pipette_right.touch_tip(v_offset=-1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify an `air_gap` to be aspirated after aspirating liquid. This, I imagine, is helpful for very low-viscosity liquids like ethanol that might otherwise leak out."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 89,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.air_gap(2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 97,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.drop_tip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Utility commands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can move directly without aspirating or dispensing. This might be helpful for bead purifications, for example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 90,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.move_to(assay['A1'].bottom())\n",
    "pipette_right.move_to(assay['A1'].top(-2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can introduce delays in the protocol:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "metadata": {},
   "outputs": [],
   "source": [
    "# can use kwargs seconds or minutes\n",
    "protocol.delay(seconds=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `pause` stops the protocol until the user presses `resume` in the app:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol.pause('Reload tips and press Resume to continue:')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And you can display messages to show context:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [],
   "source": [
    "protocol.comment('Currently doing magnetic separation')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Complex commands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are three basic complex liquid handling commands: `transfer`, `consolidate`, and `distribute.` `transfer` is the most flexible, but the latter two are convenient for some common functions. \n",
    "\n",
    "They each can be given kwargs for each of the elementary commands, but the default behaviors with respect to each [depends on the particular command](https://docs.opentrons.com/v2/new_complex_commands.html#complex-params). \n",
    "\n",
    "For example, the complex commands handle tip replacement and disposal, which you can specify using the `new_tip=['always'|'once'|'never']` argument to determine how often to get new tips, and the `trash=[True|False]` argument to determine whether to drop used tips in trash or to return them to their tip box. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### transfer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By default, this will grab the next available tip from the racks assigned to that pipette, and use it to perform the transfer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p300_multi_v1 in LEFT>"
      ]
     },
     "execution_count": 107,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_left.transfer(50, reagents['A1'], assay.wells_by_name()['A1'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For volumes larger than the max of the pipette, it will automatically do multiple transfers using the same tip:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 108,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.transfer(20, reagents['A2'], assay.wells_by_name()['A2'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One-to-one transfer commands, for copying plates, take a list of source and destination wells. This command defaults to `once` for `new_tip`, such that it will use the same tip for each transfer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 125,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 125,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.transfer(2, samples.wells(), assay.wells())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipette_right.reset_tipracks()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following version of the command does the same one-to-one transfer, but with a new tip for each well, 5x 10 µL mixing and returning the used tips to the tip rack."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 127,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in RIGHT>"
      ]
     },
     "execution_count": 127,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_right.transfer(2, \n",
    "                       samples.wells(), \n",
    "                       assay.wells(),\n",
    "                       mix_after=(5, 10),\n",
    "                       touch_tip=True,\n",
    "                       trash=False,\n",
    "                       new_tip='always')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {},
   "outputs": [],
   "source": [
    "pipette_right.reset_tipracks()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `consolidate` command picks up a little volume from each source well and combines them in the tip before ejecting the whole in the destination well. I can't think of a protocol we do that is likely to use this operation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`distribute` does the reverse, and is probably what we'd use for things like dispensing reagents. \n",
    "\n",
    "The following command will dispense 40 µL from the `reagent` plate into each well of the destination plates:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p300_multi_v1 in LEFT>"
      ]
     },
     "execution_count": 129,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pipette_left.distribute(40,\n",
    "                        reagents.wells_by_name()['A1'],\n",
    "                        assay.rows_by_name()['A'],\n",
    "                        disposal_volume=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this is called with multiple source wells, the robot will use each source well for a separate set of destination wells. I'm not sure how the logic of this works exactly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multichannel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multichannel positions are referenced with the uppermost well in a column. For 96-well plates, that would be A1-A12. For 384-well plates, it would be A1-A24 and B1-B24."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A1 of assay on 5"
      ]
     },
     "execution_count": 130,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "assay['A1']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[A1 of assay on 5, A2 of assay on 5]"
      ]
     },
     "execution_count": 131,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "[assay[x] for x in ['A1','A2']]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "assay[x] for "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}