A beginner's approach to OT-2 APIv2.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": true
   },
   "source": [
    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Introduction\" data-toc-modified-id=\"Introduction-1\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Introduction</a></span></li><li><span><a href=\"#Disclaimer\" data-toc-modified-id=\"Disclaimer-2\"><span class=\"toc-item-num\">2&nbsp;&nbsp;</span>Disclaimer</a></span></li><li><span><a href=\"#Intended-Outcomes\" data-toc-modified-id=\"Intended-Outcomes-3\"><span class=\"toc-item-num\">3&nbsp;&nbsp;</span>Intended Outcomes</a></span></li><li><span><a href=\"#(Part-I)-Preparation:-System-Setup\" data-toc-modified-id=\"(Part-I)-Preparation:-System-Setup-4\"><span class=\"toc-item-num\">4&nbsp;&nbsp;</span>(Part I) Preparation: System Setup</a></span><ul class=\"toc-item\"><li><span><a href=\"#Install-the-IDE\" data-toc-modified-id=\"Install-the-IDE-4.1\"><span class=\"toc-item-num\">4.1&nbsp;&nbsp;</span>Install the IDE</a></span></li><li><span><a href=\"#Install-the-opentrons-module\" data-toc-modified-id=\"Install-the-opentrons-module-4.2\"><span class=\"toc-item-num\">4.2&nbsp;&nbsp;</span>Install the opentrons module</a></span></li><li><span><a href=\"#Keeping-the-opentrons-module-up-to-date\" data-toc-modified-id=\"Keeping-the-opentrons-module-up-to-date-4.3\"><span class=\"toc-item-num\">4.3&nbsp;&nbsp;</span>Keeping the opentrons module up-to-date</a></span></li></ul></li><li><span><a href=\"#Setting-up-a-virtual-environment-for-simulating-a-robot\" data-toc-modified-id=\"Setting-up-a-virtual-environment-for-simulating-a-robot-5\"><span class=\"toc-item-num\">5&nbsp;&nbsp;</span>Setting up a virtual environment for simulating a robot</a></span></li><li><span><a href=\"#Labware-objects\" data-toc-modified-id=\"Labware-objects-6\"><span class=\"toc-item-num\">6&nbsp;&nbsp;</span>Labware objects</a></span><ul class=\"toc-item\"><li><span><a href=\"#Putting-labware-objects-on-the-deck\" data-toc-modified-id=\"Putting-labware-objects-on-the-deck-6.1\"><span class=\"toc-item-num\">6.1&nbsp;&nbsp;</span>Putting labware objects on the deck</a></span></li><li><span><a href=\"#Getting-wells-within-a-labware\" data-toc-modified-id=\"Getting-wells-within-a-labware-6.2\"><span class=\"toc-item-num\">6.2&nbsp;&nbsp;</span>Getting wells within a labware</a></span></li></ul></li><li><span><a href=\"#Setting-up-pipettes\" data-toc-modified-id=\"Setting-up-pipettes-7\"><span class=\"toc-item-num\">7&nbsp;&nbsp;</span>Setting up pipettes</a></span></li><li><span><a href=\"#Getting-readouts-from-the-console\" data-toc-modified-id=\"Getting-readouts-from-the-console-8\"><span class=\"toc-item-num\">8&nbsp;&nbsp;</span>Getting readouts from the console</a></span></li><li><span><a href=\"#Executing-a-simple-liquid-transfer\" data-toc-modified-id=\"Executing-a-simple-liquid-transfer-9\"><span class=\"toc-item-num\">9&nbsp;&nbsp;</span>Executing a simple liquid transfer</a></span><ul class=\"toc-item\"><li><span><a href=\"#&quot;one-to-one&quot;-transfer\" data-toc-modified-id=\"&quot;one-to-one&quot;-transfer-9.1\"><span class=\"toc-item-num\">9.1&nbsp;&nbsp;</span>\"one-to-one\" transfer</a></span></li><li><span><a href=\"#Large-volumes\" data-toc-modified-id=\"Large-volumes-9.2\"><span class=\"toc-item-num\">9.2&nbsp;&nbsp;</span>Large volumes</a></span></li><li><span><a href=\"#Scaling-up-transfer-by-the-&quot;one-to-many&quot;,-&quot;many-to-one&quot;,-or-&quot;many-to-many&quot;-transfer-modes\" data-toc-modified-id=\"Scaling-up-transfer-by-the-&quot;one-to-many&quot;,-&quot;many-to-one&quot;,-or-&quot;many-to-many&quot;-transfer-modes-9.3\"><span class=\"toc-item-num\">9.3&nbsp;&nbsp;</span>Scaling up transfer by the \"one-to-many\", \"many-to-one\", or \"many-to-many\" transfer modes</a></span></li></ul></li><li><span><a href=\"#Scaling-up-transfers-using-a-for-loop\" data-toc-modified-id=\"Scaling-up-transfers-using-a-for-loop-10\"><span class=\"toc-item-num\">10&nbsp;&nbsp;</span>Scaling up transfers using a for-loop</a></span><ul class=\"toc-item\"><li><span><a href=\"#Nested-for-loops-example\" data-toc-modified-id=\"Nested-for-loops-example-10.1\"><span class=\"toc-item-num\">10.1&nbsp;&nbsp;</span>Nested for-loops example</a></span></li></ul></li><li><span><a href=\"#Note-on-using-8-channel-pipettes\" data-toc-modified-id=\"Note-on-using-8-channel-pipettes-11\"><span class=\"toc-item-num\">11&nbsp;&nbsp;</span>Note on using 8-channel pipettes</a></span></li><li><span><a href=\"#Finalizng-the-script-for-formal-simulation-and-run\" data-toc-modified-id=\"Finalizng-the-script-for-formal-simulation-and-run-12\"><span class=\"toc-item-num\">12&nbsp;&nbsp;</span>Finalizng the script for formal simulation and run</a></span><ul class=\"toc-item\"><li><span><a href=\"#Modifying-the-script-to-make-it-executable-by-OT-2\" data-toc-modified-id=\"Modifying-the-script-to-make-it-executable-by-OT-2-12.1\"><span class=\"toc-item-num\">12.1&nbsp;&nbsp;</span>Modifying the script to make it executable by OT-2</a></span></li><li><span><a href=\"#Protocol-simulation---as-instructed-by-Opentrons\" data-toc-modified-id=\"Protocol-simulation---as-instructed-by-Opentrons-12.2\"><span class=\"toc-item-num\">12.2&nbsp;&nbsp;</span>Protocol simulation - as instructed by Opentrons</a></span></li><li><span><a href=\"#Exporting-the-log-file-for-documentation\" data-toc-modified-id=\"Exporting-the-log-file-for-documentation-12.3\"><span class=\"toc-item-num\">12.3&nbsp;&nbsp;</span>Exporting the log file for documentation</a></span></li></ul></li><li><span><a href=\"#(Part-II)-Customizing-the-liquid-transfer-process\" data-toc-modified-id=\"(Part-II)-Customizing-the-liquid-transfer-process-13\"><span class=\"toc-item-num\">13&nbsp;&nbsp;</span>(Part II) Customizing the liquid transfer process</a></span><ul class=\"toc-item\"><li><span><a href=\"#Customization-on-Transfers-using-Paramaters\" data-toc-modified-id=\"Customization-on-Transfers-using-Paramaters-13.1\"><span class=\"toc-item-num\">13.1&nbsp;&nbsp;</span>Customization on Transfers using Paramaters</a></span><ul class=\"toc-item\"><li><span><a href=\"#new_tip\" data-toc-modified-id=\"new_tip-13.1.1\"><span class=\"toc-item-num\">13.1.1&nbsp;&nbsp;</span>new_tip</a></span></li><li><span><a href=\"#mix_before-/-mix_after\" data-toc-modified-id=\"mix_before-/-mix_after-13.1.2\"><span class=\"toc-item-num\">13.1.2&nbsp;&nbsp;</span>mix_before / mix_after</a></span></li><li><span><a href=\"#disposal_volume\" data-toc-modified-id=\"disposal_volume-13.1.3\"><span class=\"toc-item-num\">13.1.3&nbsp;&nbsp;</span>disposal_volume</a></span></li></ul></li><li><span><a href=\"#Pipetting-speed\" data-toc-modified-id=\"Pipetting-speed-13.2\"><span class=\"toc-item-num\">13.2&nbsp;&nbsp;</span>Pipetting speed</a></span></li><li><span><a href=\"#Well-location\" data-toc-modified-id=\"Well-location-13.3\"><span class=\"toc-item-num\">13.3&nbsp;&nbsp;</span>Well location</a></span></li></ul></li><li><span><a href=\"#Achieving-fine-control-through-&quot;building-block&quot;-commands\" data-toc-modified-id=\"Achieving-fine-control-through-&quot;building-block&quot;-commands-14\"><span class=\"toc-item-num\">14&nbsp;&nbsp;</span>Achieving fine control through \"building block\" commands</a></span><ul class=\"toc-item\"><li><span><a href=\"#Example-1:-the-blow_out=True-issue\" data-toc-modified-id=\"Example-1:-the-blow_out=True-issue-14.1\"><span class=\"toc-item-num\">14.1&nbsp;&nbsp;</span>Example 1: the blow_out=True issue</a></span></li><li><span><a href=\"#Example-2:-Delay-between-aspiration-and-dispense\" data-toc-modified-id=\"Example-2:-Delay-between-aspiration-and-dispense-14.2\"><span class=\"toc-item-num\">14.2&nbsp;&nbsp;</span>Example 2: Delay between aspiration and dispense</a></span></li><li><span><a href=\"#Example-3:-Mixing-with-customized-speeds\" data-toc-modified-id=\"Example-3:-Mixing-with-customized-speeds-14.3\"><span class=\"toc-item-num\">14.3&nbsp;&nbsp;</span>Example 3: Mixing with customized speeds</a></span></li></ul></li><li><span><a href=\"#Writing-reusable-scripts\" data-toc-modified-id=\"Writing-reusable-scripts-15\"><span class=\"toc-item-num\">15&nbsp;&nbsp;</span>Writing reusable scripts</a></span><ul class=\"toc-item\"><li><span><a href=\"#Labware-and-pipetting-loading\" data-toc-modified-id=\"Labware-and-pipetting-loading-15.1\"><span class=\"toc-item-num\">15.1&nbsp;&nbsp;</span>Labware and pipetting loading</a></span></li><li><span><a href=\"#Reusable-pipetting-functions\" data-toc-modified-id=\"Reusable-pipetting-functions-15.2\"><span class=\"toc-item-num\">15.2&nbsp;&nbsp;</span>Reusable pipetting functions</a></span></li></ul></li><li><span><a href=\"#Manual-intergration-with-Excel\" data-toc-modified-id=\"Manual-intergration-with-Excel-16\"><span class=\"toc-item-num\">16&nbsp;&nbsp;</span>Manual intergration with Excel</a></span></li><li><span><a href=\"#Additional-remarks\" data-toc-modified-id=\"Additional-remarks-17\"><span class=\"toc-item-num\">17&nbsp;&nbsp;</span>Additional remarks</a></span></li></ul></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction\n",
    "This workshop aims at making the OT-2 APIv2 as approachable as possible for people like me who have limited experience in programming. The workshop material below is in someway just a skimmed walkthrough of the [Opentrons OT-2 APIv2 docs](http://docs.opentrons.com/v2). However, this is not meant to be a OT-2 programming 101 course and so it does not follow the official order nor their recommendations. OT-2 users who wish to make the most out of the robot are encouraged to peruse the docs.\n",
    "\n",
    "In the rest of the document, API refers to APIv2.\n",
    "\n",
    "To summarize, our approach to the API is:\n",
    "\n",
    "**First you make it work, then you make it work better**\n",
    "\n",
    "Part 1: The basics, for start to finish\n",
    "\n",
    "1. Build a virtual environment (a sandbox) to play around with features of the API  \n",
    "2. Unit test the labware, wells, pipettes and commands and get instant readouts\n",
    "3. Generate a human-trackable unit action, i.e. one single liquid transfer\n",
    "4. Loop that unit action to scale up the experiment\n",
    "5. Simulate the draft in the virtual environment, get the simulated output and check whether it is correct\n",
    "6. Remove the virtual environment and convert the draft into a proper script\n",
    "7. Do a final confirmation by simulating the script and exporting its formal runlog (**important for experiment documentation**)\n",
    "\n",
    "Part 2: Customizations, how to make our experiments really work, and how to make our lives easier\n",
    "\n",
    "1. Customize the transfer process\n",
    "2. Use building block commands to achieve control precision\n",
    "3. Write reusable scripts to avoid creating new scripts from scratch every time\n",
    "4. Semi-integrate with Microsoft Excel so outputs from other instruments could be used to direct transfer processes\n",
    "\n",
    "# Disclaimer\n",
    "1. I have limited experience in programming and received little formal training. Coding practices may be unorthodox and even heretic in the eyes of properly trained programmers.\n",
    "2. Methods of execution are in most cases suboptimal in performance. (see Additional Remarks #1)\n",
    "3. Please forgive my ocassional loss of professionalism in language.\n",
    "\n",
    "\n",
    "# Intended Outcomes\n",
    "\n",
    "By the end of the workshop, we hope participants would be able to:\n",
    "\n",
    "1. Read the documentation on APIv2, and know where to look for more information, and where to seek help if needed\n",
    "2. Install the Opentrons module\n",
    "3. Import the opentrons library to initialize a protocol object, create labware objects and pipettes within it and retrieve their information\n",
    "4. Debug the code using the variable explorer and the console\n",
    "5. Access wells of plates / racks\n",
    "6. Instruct the pipettes to carry out liquid movement using pipette.transfer() and configure it with additional parameters\n",
    "7. Create a custom pipetting step using building block commands\n",
    "8. Use loops, lists and dictionaries together to scale up pipetting steps\n",
    "9. Simulate the protocol in a PC and then converting it to a robot-executable one\n",
    "10. Export simulate results to a readable-file.\n",
    "11. Write the framework of practically useful protocols for automatable experiments \n",
    "12. Use Excel to create list of parsable commands to be copied and pasted into a protocol"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# (Part I) Preparation: System Setup\n",
    "\n",
    "## Install the IDE\n",
    "It is best to make use of an Integrated Development Environment (IDE) when writing codes. My personal experience suggests that  Spyder is most friendly to Python beginners and its Variable Explorer is tremendously helpful, both in debugging and in understanding how the API works. Some other workshops recommend Jupyter or PyCharm. Participants are welcomed to stick with the IDEs they are most comfortable with.\n",
    "\n",
    "The relatively fool-proof way to get Spyder is to download and install [Anaconda](https://www.anaconda.com/distribution/). For advanced users, the accompanying site packages like pandas and NumPy comes in handy for interfacing experiment results and experiment automation. (This will not be covered here)\n",
    "\n",
    "## Install the opentrons module\n",
    "\n",
    "Once Anaconda is installed, participants should open Spyder, and install the opentrons module / library, by typing in the IPython console:  \n",
    "\n",
    "`pip install opentrons`\n",
    "\n",
    "To check if the opentrons is correctly installed, participants should try and see if they could get the module version from the  console."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.18.0\n"
     ]
    }
   ],
   "source": [
    "import opentrons\n",
    "print(opentrons.__version__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Failure to do so should give an error message of `ModuleNotFoundError: No module named 'opentrons'`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Keeping the opentrons module up-to-date\n",
    "Opentrons update their API and library from time to time and it should happen together with OT-2 App and robot firmware upgrade. Always check if the opentrons module is the latest, and if needed, upgrade the opentrons module on the computer by typing in the terminal  \n",
    "\n",
    "`pip install opentrons --upgrade`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting up a virtual environment for simulating a robot\n",
    "\n",
    "The following section corresponds to [\"Using Python For Protocols: Simulating your scripts\"](https://docs.opentrons.com/v2/writing.html#simulating-your-scripts) from the API docs.\n",
    "\n",
    "Let's start by typing the following into the Spyder Editor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.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 simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `protocol` object is the starting point of all robot related actions, like choosing the pipette and putting labware on deck. It also stores the simulated output of the robot. To inspect its functions and attributes, run `dir(protocol)` in the IPython console."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Labware objects\n",
    "\n",
    "The following section corresponds to [\"Labware\"](https://docs.opentrons.com/v2/new_labware.html) from the Opentrons docs.\n",
    "\n",
    "## Putting labware objects on the deck\n",
    "\n",
    "Opentrons' definition of labware includes both the mult-well plates/racks/reserviors and the tip racks. They are loaded onto the robot via the function:  \n",
    "`labware_name = protocol.load_labware(load_name, location)`  \n",
    "- load_name: what is the labware, **as called by Opentrons**?  \n",
    "To look up this information, go to the [Opentrons official labware page](https://labware.opentrons.com/).\n",
    "In the following example we will use a [200 µL 96-well flat bottom plate](https://labware.opentrons.com/corning_96_wellplate_360ul_flat).  \n",
    "The `load_name` of this labware is `corning_96_wellplate_360ul_flat`.  \n",
    "See Additional Remarks 3 for using a generic versus specific `load_name`.  \n",
    "  \n",
    "  \n",
    "- slot: which of the slot (1-11) are we placing it?  \n",
    "This argument can be input as an integer or a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now if we inspect the variable explorer we should see the an object of `plate` being created. Any labware objects that we load by this command exists as a virtual object in the simulated environment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Corning 96 Well Plate 360 µL Flat on 1"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Again, we can double click on the object in the variable explorer or use `dir(plate)` to look at the attributes of this plate.  \n",
    "  \n",
    "We also need to put tips and tip racks onto the deck (say slot 2). So we will add and run the following lines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It should also appear in the variable explorer, can be checked just by typing the variable in the console."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Opentrons 96 Tip Rack 300 µL on 2"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tip_rack"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting wells within a labware\n",
    "\n",
    "Before adding the pipettes let's briefy talk about how to get the wells in a labware object. This applies to whatever labware we are using, whether it's a multi-well plate or a tube rack or even a tip rack.\n",
    "\n",
    "The [\"Labware: Accessor Methods\"](https://docs.opentrons.com/v2/new_labware.html#accessor-methods) section on the Opentrons docs provide multiple ways to get the wells on labware, but we will only introduce two methods, which are usually sufficient to deal with most situations.\n",
    "\n",
    "The conventional or user-firendly way: `labware.wells_by_name()[well_name]`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A6 of Corning 96 Well Plate 360 µL Flat on 1"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# get a single well\n",
    "plate.wells_by_name()['A6']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A6 of Corning 96 Well Plate 360 µL Flat on 1"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# get a single well and assign it to a variable\n",
    "sample_well = plate.wells_by_name()['A6']\n",
    "sample_well"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The other way is that get the wells by their **well indices**. This can come in handy in some other situations.  \n",
    "  \n",
    "Method: `labware.wells()[well_index]`\n",
    "\n",
    "Well index for a 96-well format:\n",
    "\n",
    "\n",
    "|   | 1 | 2  | 3  | 4  | 5  | 6  | 7  | 8  | 9  | 10 | 11 | 12 |\n",
    "|---|---|----|----|----|----|----|----|----|----|----|----|----|\n",
    "| A | 0 | 8  | 16 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 88 |\n",
    "| B | 1 | 9  | 17 | 25 | 33 | 41 | 49 | 57 | 65 | 73 | 81 | 89 |\n",
    "| C | 2 | 10 | 18 | 26 | 34 | 42 | 50 | 58 | 66 | 74 | 82 | 90 |\n",
    "| D | 3 | 11 | 19 | 27 | 35 | 43 | 51 | 59 | 67 | 75 | 83 | 91 |\n",
    "| E | 4 | 12 | 20 | 28 | 36 | 44 | 52 | 60 | 68 | 76 | 84 | 92 |\n",
    "| F | 5 | 13 | 21 | 29 | 37 | 45 | 53 | 61 | 69 | 77 | 85 | 93 |\n",
    "| G | 6 | 14 | 22 | 30 | 38 | 46 | 54 | 62 | 70 | 78 | 86 | 94 |\n",
    "| H | 7 | 15 | 23 | 31 | 39 | 47 | 55 | 63 | 71 | 79 | 87 | 95 |\n",
    "\n",
    "Well index for a 24-well format (whether tube rack or 24-well plate):\n",
    "\n",
    "|   | 1 | 2 | 3  | 4  | 5  | 6  |\n",
    "|---|---|---|----|----|----|----|\n",
    "| A | 0 | 4 | 8  | 12 | 16 | 20 |\n",
    "| B | 1 | 5 | 9  | 13 | 17 | 21 |\n",
    "| C | 2 | 6 | 10 | 14 | 18 | 22 |\n",
    "| D | 3 | 7 | 11 | 15 | 19 | 23 |"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A6 of Corning 96 Well Plate 360 µL Flat on 1"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get well A6 in 96-well plate\n",
    "plate.wells()[40]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "A6 of Corning 24 Well Plate 3.4 mL Flat on 3"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get well A6 in 24-well plate\n",
    "plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 3)\n",
    "plate2.wells()[20]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One advantage of using well index instead of well name, is that we can easily get a **continuous** list of wells by inputing a \"slice\" of the list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[A1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " B1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " C1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " D1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " E1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " F1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " G1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " H1 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " A2 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " B2 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " C2 of Corning 96 Well Plate 360 µL Flat on 1,\n",
       " D2 of Corning 96 Well Plate 360 µL Flat on 1]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plate.wells()[0:12]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we **cannot** use these methods to get mulitple specific wells"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "KeyError",
     "evalue": "('A1', 'B2', 'C3')",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m--------------------------------------------------\u001b[0m",
      "\u001b[1;31mKeyError\u001b[0m         Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-12-ca2a01c16800>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m      1\u001b[0m \u001b[1;31m# Wrong way to get multiple wells by the .wells_by_name()\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m----> 2\u001b[1;33m \u001b[0mplate\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells_by_name\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'A1'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'B2'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'C3'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mKeyError\u001b[0m: ('A1', 'B2', 'C3')"
     ]
    }
   ],
   "source": [
    "# Wrong way to get multiple wells by the .wells_by_name()\n",
    "plate.wells_by_name()['A1', 'B2', 'C3']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "TypeError",
     "evalue": "list indices must be integers or slices, not tuple",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m--------------------------------------------------\u001b[0m",
      "\u001b[1;31mTypeError\u001b[0m        Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-13-b3439485b881>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m      1\u001b[0m \u001b[1;31m# Wrong way to get multiple wells by the .wells()\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m----> 2\u001b[1;33m \u001b[0mplate\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;36m1\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;36m2\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;36m3\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[1;31mTypeError\u001b[0m: list indices must be integers or slices, not tuple"
     ]
    }
   ],
   "source": [
    "# Wrong way to get multiple wells by the .wells()\n",
    "plate.wells()[1, 2, 3]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setting up pipettes\n",
    "\n",
    "The following section corresponds to [\"Pipettes: Loading A Pipette\"](https://docs.opentrons.com/v2/new_pipette.html#loading-a-pipette) from the API docs.\n",
    "\n",
    "The way to set up a pipette is to call the function: `pipette_name = protocol.load_instrument(instrumnt_name, mount, tip_racks)`\n",
    "\n",
    "Refer to the [\"Pipettes: Pipette Models\"](https://docs.opentrons.com/v2/new_pipette.html#pipette-models) for what instrument_name corresponds to what pipette.\n",
    "\n",
    "Note 1: The argument `tip_racks` must be a **list**, this is a mistake I often make.\n",
    "\n",
    "Note 2 : **Always** load the tip racks onto the virtual deck beforehand and **associate then those tip racks with the pipette** when we set up the pipette."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p300_single_v1 in RIGHT>"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# load a P300S on the right mount\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single', # instrument_name\n",
    "    'right', # mount\n",
    "    tip_racks=[tip_rack] # tip_racks as list, note that we are re-using the tip_rack object loaded before\n",
    ")\n",
    "\n",
    "r_pipette"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<InstrumentContext: p10_multi_v1 in LEFT>"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Similarily, we can load a P10M on the left mount\n",
    "# Remember to load a compatible tip rack first.\n",
    "\n",
    "tip_rack_10 = protocol.load_labware('opentrons_96_tiprack_10ul', 4)\n",
    "\n",
    "l_pipette = protocol.load_instrument(\n",
    "    'p10_multi',\n",
    "    'left',\n",
    "    tip_racks=[tip_rack_10]\n",
    ")\n",
    "\n",
    "l_pipette"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the following examples we will stick with the P300S on the right mount only."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting readouts from the console\n",
    "\n",
    "Basically by this time we have configured the robot properly. We can then instruct the pipette to take actions.  \n",
    "  \n",
    "Before we move on to introduce the pipette commands, we will first include the following lines at the end of the script:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This line prints all the commands from the robot and will help us debug what is going on inside the script.\n",
    "\n",
    "By this time, our script should look like the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "#%% Robot set up\n",
    "\n",
    "# we slightly rearranged the locations\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 2)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single', # instrument_name\n",
    "    'right', # mount\n",
    "    tip_racks=[tip_rack] # tip_racks as list, note that we are re-using the tip_rack object loaded before\n",
    ")\n",
    "\n",
    "#%% Robot actions\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There is nothing from the console yet because we haven't assigned any commands to the pipettes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Executing a simple liquid transfer\n",
    "\n",
    "The following section corresponds to [\"Complex commands: Transfer\"](https://docs.opentrons.com/v2/new_complex_commands.html#transfer) from the API docs.\n",
    "\n",
    "We will only introduce the `pipette.transfer()` command since it is most versatile. There is really no need to use `pipette.distribute()` or `pipette.consolidate()` since `pipette.transfer()` covers those functions already, unless it's for script readability.\n",
    "\n",
    "The function should be called as follow:\n",
    "`pipette.transfer(volume, source, dest)`\n",
    "\n",
    "*Note: for this notebook the `print(protocol.commands())` function and the `protocol.clear_commands()` functions are called in every cell. This is not necessary when debugging the script in Spyder*\n",
    "\n",
    "## \"one-to-one\" transfer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, # volume in µL\n",
    "                 plate2.wells_by_name()['A1'], # source well\n",
    "                 plate1.wells_by_name()['A1'] # dest well\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The output lines above are the instructions that the robot will execute, written in a human readable format. This is the log of the simuation and we should use that to check whether we wrote the script correctly.  \n",
    "  \n",
    "The first line \"Transferring ... Flat on 1\" is actually a section header that encapsulates all the subcommands (or building block commands) that follow it. We will introduce building commands later.\n",
    "\n",
    "We can run another transfer step and pipette another 200 µL, but this time to well A2 on the 96-well plate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# a second transfer step\n",
    "\n",
    "r_pipette.transfer(200, # volume in µL\n",
    "                 plate2.wells_by_name()['A1'], # source well\n",
    "                 plate1.wells_by_name()['A2'] # dest well\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Reading the output above we take note of two things:\n",
    "\n",
    "1. Two output commands are displayed instead of one. This is because the robot keeps on remembering new instructions that we have given it. This is usually not a problem when debugging in Spyder but one should always watch out for unintended duplciation of pipetting steps while writing the script.  \n",
    "  \n",
    "  \n",
    "2. We notice that in the 1st step, the pipette picks the tip from position A1 of the rack and in the 2nd step, it does so from position B1. This is the perk of associating a tip rack to the pipette during the `load_instrument()` function, i.e., the robot automatically keep tracks of tip usage (column by column from A1 to A8, B1 to B8...)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Large volumes\n",
    "\n",
    "If we need to transfer, say, 400 µL but we only have a P300S, the `pipette.transfer()` function automatically does the calculation and performs two transfer steps of 200 µL each."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 400.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(400, # volume in µL\n",
    "                 plate2.wells_by_name()['A1'], # source well\n",
    "                 plate1.wells_by_name()['A2'] # dest well\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Scaling up transfer by the \"one-to-many\", \"many-to-one\", or \"many-to-many\" transfer modes\n",
    "\n",
    "The `pipette.transfer()` function is extremely versatile. See the following examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# one-to-many\n",
    "r_pipette.transfer(200,\n",
    "                 plate2.wells_by_name()['A1'],\n",
    "                 [\n",
    "                     plate1.wells_by_name()['A1'],\n",
    "                     plate1.wells_by_name()['A2'],\n",
    "                     plate1.wells_by_name()['A3'] # instead of a single well, pass a list of destination wells\n",
    "                 ] # notice where the open and close brackets are\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A2 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A3 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# many-to-one\n",
    "\n",
    "r_pipette.transfer(200,\n",
    "                 [\n",
    "                     plate2.wells_by_name()['A1'],\n",
    "                     plate2.wells_by_name()['A2'],\n",
    "                     plate2.wells_by_name()['A3'] # instead of a single well, pass a list of destination wells\n",
    "                 ], # again, notice where the open and close brackets are\n",
    "                plate1.wells_by_name()['A1']\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from F1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from A3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# many-to-many\n",
    "# A1 -> B1, A2 -> B2, A3 -> B3,\n",
    "\n",
    "r_pipette.transfer(200,\n",
    "                 [\n",
    "                     plate1.wells_by_name()['A1'],\n",
    "                     plate1.wells_by_name()['A2'],\n",
    "                     plate1.wells_by_name()['A3'] # a list of source wells\n",
    "                 ],\n",
    "                 [\n",
    "                     plate1.wells_by_name()['B1'],\n",
    "                     plate1.wells_by_name()['B2'],\n",
    "                     plate1.wells_by_name()['B3'] # a list of destination wells\n",
    "                 ]\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When using many-to-many transfer mode, make sure that we have **equal numbers of source and destination wells**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "scrolled": true,
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "Source and destination lists must be divisible",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m--------------------------------------------------\u001b[0m",
      "\u001b[1;31mValueError\u001b[0m       Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-24-e59363f8acf2>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m     10\u001b[0m                  [\n\u001b[0;32m     11\u001b[0m                      \u001b[0mplate1\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells_by_name\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'B1'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 12\u001b[1;33m                      \u001b[0mplate1\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells_by_name\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'B2'\u001b[0m\u001b[1;33m]\u001b[0m \u001b[1;31m# but only 2 destination wells\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     13\u001b[0m                  ]\n\u001b[0;32m     14\u001b[0m                 )\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\util.py\u001b[0m in \u001b[0;36mdecorated\u001b[1;34m(*args, **kwargs)\u001b[0m\n\u001b[0;32m    608\u001b[0m                 do_publish(\n\u001b[0;32m    609\u001b[0m                     broker, command, f, 'before', None, meta, *args, **kwargs)\n\u001b[1;32m--> 610\u001b[1;33m             \u001b[0mres\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mf\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    611\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0mafter\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    612\u001b[0m                 do_publish(\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\util.py\u001b[0m in \u001b[0;36m_check_version_wrapper\u001b[1;34m(*args, **kwargs)\u001b[0m\n\u001b[0;32m    347\u001b[0m                     \u001b[1;34mf'must increase your API version to {added_in} to '\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    348\u001b[0m                     'use this functionality.')\n\u001b[1;32m--> 349\u001b[1;33m             \u001b[1;32mreturn\u001b[0m \u001b[0mdecorated_obj\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    350\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    351\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0m_check_version_wrapper\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\instrument_context.py\u001b[0m in \u001b[0;36mtransfer\u001b[1;34m(self, volume, source, dest, trash, **kwargs)\u001b[0m\n\u001b[0;32m   1001\u001b[0m                                       \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mapi_version\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mkwargs\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'mode'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   1002\u001b[0m                                       transfer_options)\n\u001b[1;32m-> 1003\u001b[1;33m         \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_execute_transfer\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mplan\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m   1004\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   1005\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\instrument_context.py\u001b[0m in \u001b[0;36m_execute_transfer\u001b[1;34m(self, plan)\u001b[0m\n\u001b[0;32m   1005\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   1006\u001b[0m     \u001b[1;32mdef\u001b[0m \u001b[0m_execute_transfer\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mplan\u001b[0m\u001b[1;33m:\u001b[0m \u001b[0mtransfers\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mTransferPlan\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m-> 1007\u001b[1;33m         \u001b[1;32mfor\u001b[0m \u001b[0mcmd\u001b[0m \u001b[1;32min\u001b[0m \u001b[0mplan\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m   1008\u001b[0m             \u001b[0mgetattr\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mcmd\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'method'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0mcmd\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'args'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mcmd\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'kwargs'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   1009\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m__iter__\u001b[1;34m(self)\u001b[0m\n\u001b[0;32m    426\u001b[0m         yield from {TransferMode.CONSOLIDATE: self._plan_consolidate,\n\u001b[0;32m    427\u001b[0m                     \u001b[0mTransferMode\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mDISTRIBUTE\u001b[0m\u001b[1;33m:\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_plan_distribute\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 428\u001b[1;33m                     TransferMode.TRANSFER: self._plan_transfer}[self._mode]()\n\u001b[0m\u001b[0;32m    429\u001b[0m         \u001b[1;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_strategy\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mnew_tip\u001b[0m \u001b[1;33m==\u001b[0m \u001b[0mtypes\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mTransferTipPolicy\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mONCE\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    430\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_strategy\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mdrop_tip_strategy\u001b[0m \u001b[1;33m==\u001b[0m \u001b[0mDropTipStrategy\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mRETURN\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m_plan_transfer\u001b[1;34m(self)\u001b[0m\n\u001b[0;32m    466\u001b[0m         \u001b[1;31m# reform source target lists\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    467\u001b[0m         sources, dests = self._extend_source_target_lists(\n\u001b[1;32m--> 468\u001b[1;33m             self._sources, self._dests)\n\u001b[0m\u001b[0;32m    469\u001b[0m         plan_iter = self._expand_for_volume_constraints(\n\u001b[0;32m    470\u001b[0m             \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_volumes\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mzip\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msources\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mdests\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m_extend_source_target_lists\u001b[1;34m(sources, targets)\u001b[0m\n\u001b[0;32m    502\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0mlen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msources\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;33m%\u001b[0m \u001b[0mlen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mtargets\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;33m!=\u001b[0m \u001b[1;36m0\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    503\u001b[0m                 raise ValueError(\n\u001b[1;32m--> 504\u001b[1;33m                     'Source and destination lists must be divisible')\n\u001b[0m\u001b[0;32m    505\u001b[0m             targets = [target for target in targets\n\u001b[0;32m    506\u001b[0m                        for i in range(int(len(sources)/len(targets)))]\n",
      "\u001b[1;31mValueError\u001b[0m: Source and destination lists must be divisible"
     ]
    }
   ],
   "source": [
    "# many-to-many, failed example\n",
    "# A1 -> B1, A2 -> B2, A3 -> ?,\n",
    "\n",
    "r_pipette.transfer(200,\n",
    "                 [\n",
    "                     plate1.wells_by_name()['A1'],\n",
    "                     plate1.wells_by_name()['A2'],\n",
    "                     plate1.wells_by_name()['A3'] # 3 source wells\n",
    "                 ],\n",
    "                 [\n",
    "                     plate1.wells_by_name()['B1'],\n",
    "                     plate1.wells_by_name()['B2'] # but only 2 destination wells\n",
    "                 ]\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()\n",
    "\n",
    "# Look at error below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    }
   ],
   "source": [
    "# This cell resets the robot from the error, this is not required in Spyder\n",
    "\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "#%% Robot set up\n",
    "\n",
    "# we slightly rearranged the locations\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 2)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single', # instrument_name\n",
    "    'right', # mount\n",
    "    tip_racks=[tip_rack] # tip_racks as list\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we arrange the wells such that they are continuous along columns, using well indices would come in really handy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from C1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into C2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from D1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into D2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# many-to-many, along a column\n",
    "# A1 -> A2,\n",
    "# B1 -> B2,\n",
    "# C1 -> C2,\n",
    "# D1 -> D2\n",
    "\n",
    "r_pipette.transfer(200,\n",
    "                   plate1.wells()[0:4],\n",
    "                   plate1.wells()[8:12]\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Scaling up transfers using a for-loop\n",
    "\n",
    "We can now repeat a single one-to-one transfer step over and over again. This is the biggest advantage of programming through the API, compared to the Protocol Designer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "protocol.clear_commands()\n",
    "\n",
    "for i in range(3):\n",
    "    r_pipette.transfer(200, # volume in µL\n",
    "                     plate2.wells_by_name()['A1'], # source well\n",
    "                     plate1.wells_by_name()['A2'] # dest well\n",
    "                    )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the identical action is repeated three times but every time a new tip is used.  \n",
    "  \n",
    "Repeating the identical step over and over again isn't very useful, however. Very often we want to do a one-to-many or many-to-many transfer. We can modify the scripts above to do the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from F1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B3 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from G1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B4 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from H1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B4 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# one-to-many, essentially a pipette.distribute() process\n",
    "# A1 -> B1, B2, B3, B4\n",
    "\n",
    "protocol.clear_commands()\n",
    "\n",
    "dest_wells = ['B1', 'B2', 'B3', 'B4']\n",
    "\n",
    "for dest_well in dest_wells:\n",
    "    r_pipette.transfer(200,\n",
    "                     plate1.wells_by_name()['A1'],\n",
    "                     plate1.wells_by_name()[ dest_well ] # dynamic dest well that changes on every loop\n",
    "                    )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A2 of Corning 96 Well Plate 360 µL Flat on 1 to B2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from B2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A3 of Corning 96 Well Plate 360 µL Flat on 1 to B3 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from C2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A4 of Corning 96 Well Plate 360 µL Flat on 1 to B4 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from D2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A4 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B4 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# many-to-many\n",
    "# A1 -> B1,\n",
    "# A2 -> B2,\n",
    "# A3 -> B3,\n",
    "# A4 -> B4\n",
    "\n",
    "protocol.clear_commands()\n",
    "\n",
    "source_wells = ['A1', 'A2', 'A3', 'A4']\n",
    "dest_wells = ['B1', 'B2', 'B3', 'B4']\n",
    "\n",
    "for i in range(4):\n",
    "    r_pipette.transfer(200,\n",
    "                     plate1.wells_by_name()[ source_wells[i] ], # dynamic source well that changes on every loop\n",
    "                     plate1.wells_by_name()[ dest_wells[i] ] # dynamic dest well that changes on every loop\n",
    "                    )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Nested for-loops example\n",
    "\n",
    "The above examples are equivalents of the `pipette.transfer()` function, but there is more that we can achieve with for-loops.\n",
    "\n",
    "Consider the following example. We wish to pipette:\n",
    "\n",
    "plate 1 well A1 to plate 1 well A1,\n",
    "plate 1 well A2 to plate 1 well A2,\n",
    "plate 1 well A3 to plate 1 well A3,\n",
    "plate 1 well A4 to plate 1 well A4,\n",
    "\n",
    "and then repeat the same process but substituting plate 1 with plate 2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from E2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A2 of Corning 96 Well Plate 360 µL Flat on 1 to B2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from F2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A3 of Corning 96 Well Plate 360 µL Flat on 1 to B3 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from G2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B3 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A4 of Corning 96 Well Plate 360 µL Flat on 1 to B4 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from H2 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A4 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B4 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to B1 of Corning 24 Well Plate 3.4 mL Flat on 2\n",
      "Picking up tip from A3 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A2 of Corning 24 Well Plate 3.4 mL Flat on 2 to B2 of Corning 24 Well Plate 3.4 mL Flat on 2\n",
      "Picking up tip from B3 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A2 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into B2 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A3 of Corning 24 Well Plate 3.4 mL Flat on 2 to B3 of Corning 24 Well Plate 3.4 mL Flat on 2\n",
      "Picking up tip from C3 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A3 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into B3 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A4 of Corning 24 Well Plate 3.4 mL Flat on 2 to B4 of Corning 24 Well Plate 3.4 mL Flat on 2\n",
      "Picking up tip from D3 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A4 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dispensing 200.0 uL into B4 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# many-to-many,\n",
    "# for plate 1 and plate 2\n",
    "# A1 -> B1,\n",
    "# A2 -> B2,\n",
    "# A3 -> B3,\n",
    "# A4 -> B4\n",
    "\n",
    "protocol.clear_commands()\n",
    "\n",
    "source_wells = ['A1', 'A2', 'A3', 'A4']\n",
    "dest_wells = ['B1', 'B2', 'B3', 'B4']\n",
    "\n",
    "for plate in [plate1, plate2]:\n",
    "    \n",
    "    # the for-loop beneath will run twice\n",
    "    for i in range(4):\n",
    "        r_pipette.transfer(200,\n",
    "                         plate.wells_by_name()[ source_wells[i] ],\n",
    "                           # note that it is now a variable \"plate\" instead of the  object \"plate1\"\n",
    "                         plate.wells_by_name()[ dest_wells[i] ] \n",
    "                        )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Note on using 8-channel pipettes\n",
    "\n",
    "8-channel pipettes deal with 8 wells at the same time so for a `pipette.transfer` we can pass in a list of 8 well objects as the argument for `location`. We can also just assume the 8-channel pipette as a single channel pipette and use the top channel as the pointer.\n",
    "\n",
    "Example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 2\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# Alternative 1: specifying 8 wells.\n",
    "\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 2)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_multi', # we use a 8-channel pipette here\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")\n",
    "r_pipette.transfer(200,\n",
    "                   plate1.wells()[0:8], # wells A1-H1, or we can use plate1.columns_by_name()['1']\n",
    "                   plate1.wells()[8:16] # wells A2-H2, or we can use plate1.columns_by_name()['2']\n",
    "                      )\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 2\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# Alternative 2: specifying the top well only\n",
    "\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 2)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_multi', # we use a 8-channel pipette here\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")\n",
    "r_pipette.transfer(200,\n",
    "                   plate1.wells()[0], # well A1\n",
    "                   plate1.wells()[8] # well A2\n",
    "                  )\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the there are no differences between the two methods. Usually, it is best to go for \"specifying a single well\". It works more relaibly in case you need to use a 8-channel pipette with a 384-well plate.\n",
    "\n",
    "However, if the for-loop is used, we **must not loop through the groups of wells inside the `pipette.transfer()` function**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "scrolled": true,
    "tags": [
     "raises-exception"
    ]
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "ename": "RuntimeError",
     "evalue": "Invalid target for multichannel transfer: [B2 of Corning 96 Well Plate 360 µL Flat on 1]",
     "output_type": "error",
     "traceback": [
      "\u001b[1;31m--------------------------------------------------\u001b[0m",
      "\u001b[1;31mRuntimeError\u001b[0m     Traceback (most recent call last)",
      "\u001b[1;32m<ipython-input-33-338aec60f129>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m\u001b[0m\n\u001b[0;32m     16\u001b[0m     r_pipette.transfer(200,\n\u001b[0;32m     17\u001b[0m                        \u001b[0mplate1\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;36m0\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m---> 18\u001b[1;33m                        \u001b[0mplate1\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mwells\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m[\u001b[0m\u001b[0mi\u001b[0m\u001b[1;33m]\u001b[0m \u001b[1;31m# the intention may be wells in column '2', but this\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m     19\u001b[0m                       )\n\u001b[0;32m     20\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\util.py\u001b[0m in \u001b[0;36mdecorated\u001b[1;34m(*args, **kwargs)\u001b[0m\n\u001b[0;32m    608\u001b[0m                 do_publish(\n\u001b[0;32m    609\u001b[0m                     broker, command, f, 'before', None, meta, *args, **kwargs)\n\u001b[1;32m--> 610\u001b[1;33m             \u001b[0mres\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mf\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    611\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0mafter\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    612\u001b[0m                 do_publish(\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\util.py\u001b[0m in \u001b[0;36m_check_version_wrapper\u001b[1;34m(*args, **kwargs)\u001b[0m\n\u001b[0;32m    347\u001b[0m                     \u001b[1;34mf'must increase your API version to {added_in} to '\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    348\u001b[0m                     'use this functionality.')\n\u001b[1;32m--> 349\u001b[1;33m             \u001b[1;32mreturn\u001b[0m \u001b[0mdecorated_obj\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;33m*\u001b[0m\u001b[0margs\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;33m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    350\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    351\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0m_check_version_wrapper\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\instrument_context.py\u001b[0m in \u001b[0;36mtransfer\u001b[1;34m(self, volume, source, dest, trash, **kwargs)\u001b[0m\n\u001b[0;32m   1000\u001b[0m         plan = transfers.TransferPlan(volume, source, dest, self, max_volume,\n\u001b[0;32m   1001\u001b[0m                                       \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mapi_version\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mkwargs\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'mode'\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m-> 1002\u001b[1;33m                                       transfer_options)\n\u001b[0m\u001b[0;32m   1003\u001b[0m         \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_execute_transfer\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mplan\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m   1004\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m__init__\u001b[1;34m(self, volume, sources, dests, instr, max_volume, api_version, mode, options)\u001b[0m\n\u001b[0;32m    383\u001b[0m         \u001b[1;31m# list of Wells into a 1 dimensional list of Wells\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    384\u001b[0m         \u001b[1;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_instr\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mhw_pipette\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;34m'channels'\u001b[0m\u001b[1;33m]\u001b[0m \u001b[1;33m>\u001b[0m \u001b[1;36m1\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 385\u001b[1;33m             \u001b[0msources\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mdests\u001b[0m \u001b[1;33m=\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_multichannel_transfer\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msources\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mdests\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    386\u001b[0m         \u001b[1;32melse\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    387\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0misinstance\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msources\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mList\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;32mand\u001b[0m \u001b[0misinstance\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0msources\u001b[0m\u001b[1;33m[\u001b[0m\u001b[1;36m0\u001b[0m\u001b[1;33m]\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mList\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m_multichannel_transfer\u001b[1;34m(self, s, d)\u001b[0m\n\u001b[0;32m    823\u001b[0m             \u001b[1;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_is_valid_row\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mwell\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    824\u001b[0m                 \u001b[0mnew_dst\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0mappend\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mwell\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[1;32m--> 825\u001b[1;33m         \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_check_valid_well_list\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mnew_dst\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;34m'target'\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0md\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m    826\u001b[0m         \u001b[1;32mreturn\u001b[0m \u001b[0mnew_src\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0mnew_dst\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    827\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;32mD:\\Anaconda\\lib\\site-packages\\opentrons\\protocol_api\\transfers.py\u001b[0m in \u001b[0;36m_check_valid_well_list\u001b[1;34m(self, well_list, id, old_well_list)\u001b[0m\n\u001b[0;32m    784\u001b[0m         \u001b[1;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[1;33m.\u001b[0m\u001b[0m_api_version\u001b[0m \u001b[1;33m>=\u001b[0m \u001b[0mAPIVersion\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;36m2\u001b[0m\u001b[1;33m,\u001b[0m \u001b[1;36m2\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;32mand\u001b[0m \u001b[0mlen\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mwell_list\u001b[0m\u001b[1;33m)\u001b[0m \u001b[1;33m<\u001b[0m \u001b[1;36m1\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    785\u001b[0m             raise RuntimeError(\n\u001b[1;32m--> 786\u001b[1;33m                 f\"Invalid {id} for multichannel transfer: {old_well_list}\")\n\u001b[0m\u001b[0;32m    787\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m    788\u001b[0m     \u001b[1;32mdef\u001b[0m \u001b[0m_multichannel_transfer\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mself\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0ms\u001b[0m\u001b[1;33m,\u001b[0m \u001b[0md\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
      "\u001b[1;31mRuntimeError\u001b[0m: Invalid target for multichannel transfer: [B2 of Corning 96 Well Plate 360 µL Flat on 1]"
     ]
    }
   ],
   "source": [
    "# Wrong example of for-loop together with 8-channel pipette.\n",
    "\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 2)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_multi', # we use a 8-channel pipette here\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")\n",
    "\n",
    "for i in [8, 9 ,10, 11, 12, 13, 14, 15, 16]:\n",
    "    r_pipette.transfer(200,\n",
    "                       plate1.wells()[0],\n",
    "                       plate1.wells()[i] # the intention may be wells in column '2', but this \n",
    "                      )\n",
    "    \n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Finalizng the script for formal simulation and run\n",
    "\n",
    "It should be noted that we have so far simulated our pipettes, labware and commands in a virtual environment, but since the `protocol` object we created was virtual, it cannot be transferred to an actual robot for execution. We will have to make some modifications on our script to make it a proper script.\n",
    "\n",
    "## Modifying the script to make it executable by OT-2\n",
    "\n",
    "Say we have a simulated script below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "outputs": [],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 2)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single',\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")\n",
    "\n",
    "r_pipette.transfer(200,\n",
    "                 plate2.wells_by_name()['A1'],\n",
    "                 plate1.wells_by_name()['A1']\n",
    "                )\n",
    "\n",
    "r_pipette.transfer(150,\n",
    "                 plate2.wells_by_name()['A1'],\n",
    "                 plate1.wells_by_name()['A2']\n",
    "                )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we look at an example script as shown on the [Opentrons Docs](https://docs.opentrons.com/v2/#how-it-looks), we will notce a few key differences."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "outputs": [],
   "source": [
    "from opentrons import protocol_api\n",
    "\n",
    "# metadata\n",
    "metadata = {\n",
    "    'protocolName': 'My Protocol',\n",
    "    'author': 'Name <email@address.com>',\n",
    "    'description': 'Simple protocol to get started using OT2',\n",
    "    'apiLevel': '2.2'\n",
    "}\n",
    "\n",
    "# protocol run function. the part after the colon lets your editor know\n",
    "# where to look for autocomplete suggestions\n",
    "def run(protocol: protocol_api.ProtocolContext):\n",
    "\n",
    "    # labware\n",
    "    plate = protocol.load_labware('corning_96_wellplate_360ul_flat', '2')\n",
    "    tiprack = protocol.load_labware('opentrons_96_tiprack_300ul', '1')\n",
    "\n",
    "    # pipettes\n",
    "    left_pipette = protocol.load_instrument(\n",
    "         'p300_single', 'left', tip_racks=[tiprack])\n",
    "\n",
    "    # commands\n",
    "    left_pipette.pick_up_tip()\n",
    "    left_pipette.aspirate(100, plate['A1'])\n",
    "    left_pipette.dispense(100, plate['B2'])\n",
    "    left_pipette.drop_tip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. There is a line of `from opentrons import protocol_api`, and there are no lines related to `opentrons.simulate`, or `print(protocol.commands())`.\n",
    "\n",
    "2. There is a metadata dictionary\n",
    "This is mostly for Opentrons to collect your personal data. You could leave everything out but you **must at least keep the 'apiLevel'**\n",
    "\n",
    "3. Everything related to the robot (labware, pipettes and commands) are wrapped under a function `run()`\n",
    "\n",
    "So to make the script executable on a robot, we have to make the above changes.\n",
    "\n",
    "Tip: instead of deleting lines, **comment them out** by highlighting the text and press `Ctrl` + `1` in Spyder.  \n",
    "Caution: wrapping codes with a function means that they have to be **indented**. Highlight the code and press the `Tab` key will do the job. To unindent, highlight the text and press `Shift` + `Tab`.\n",
    "\n",
    "If we make the above changes, our script will now look like the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "deletable": false,
    "editable": false,
    "run_control": {
     "frozen": true
    }
   },
   "outputs": [],
   "source": [
    "# from opentrons import simulate\n",
    "# protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "from opentrons import protocol_api\n",
    "\n",
    "metadata = {\n",
    "    'apiLevel': '2.4'\n",
    "}\n",
    "\n",
    "def run(protocol: protocol_api.ProtocolContext):\n",
    "\n",
    "    plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "    plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 2)\n",
    "    tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "    r_pipette = protocol.load_instrument(\n",
    "        'p300_single',\n",
    "        'right',\n",
    "        tip_racks=[tip_rack]\n",
    "    )\n",
    "\n",
    "    r_pipette.transfer(200,\n",
    "                 plate2.wells_by_name()['A1'],\n",
    "                 plate1.wells_by_name()['A1']\n",
    "                )\n",
    "\n",
    "    r_pipette.transfer(150,\n",
    "                 plate2.wells_by_name()['A1'],\n",
    "                 plate1.wells_by_name()['A2']\n",
    "                )\n",
    "\n",
    "# print(*protocol.commands(), sep = '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this format, our script is now ready to be executed on a robot.\n",
    "\n",
    "But hold on, we should keep a simulated log for the experiment. If the protocol went awry, we can inspect a simulated log file to figure out whether we made mistakes in the code. However, after making these changes we cannot directly run the script in Spyder and get readouts, since the script is not designed to.\n",
    "\n",
    "## Protocol simulation - as instructed by Opentrons\n",
    "\n",
    "The following section corresponds to [\"Using Python For Protocols: Simulating Your Scripts: In the Python Shell\"](https://docs.opentrons.com/v2/writing.html#in-the-python-shell) from the API docs.\n",
    "\n",
    "To simulate the script in an officially recommended way, we will first save our script above as .py file. We will name it \"Test_script.py\". Then, we will create another .py file in the same folder, and we will name it \"simulate.py\", and type in the following lines:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "C:\\Users\\User\\.opentrons\\deck_calibration.json not found. Loading defaults\n",
      "C:\\Users\\User\\.opentrons\\robot_settings.json not found. Loading defaults\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "\tPicking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "\tAspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "\tDispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "\tDropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 150.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "\tPicking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "\tAspirating 150.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "\tDispensing 150.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "\tDropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "from opentrons.simulate import simulate, format_runlog\n",
    "protocol_filename = 'Test_script.py' # TODO: change this for a new file\n",
    "protocol_file = open(protocol_filename)\n",
    "runlog = simulate(protocol_file, file_name='')\n",
    "print(format_runlog(runlog[0])) # Line modified compared to Opentrons Doc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see above that the log is nicely displayed. The building block commands within a complex command are indented for better readability. So why don't we create our script this way?\n",
    "\n",
    "In fact, we could. However, it will make debugging much more complicated. So it is **not recommended**.\n",
    "\n",
    "## Exporting the log file for documentation\n",
    "\n",
    "We can further expand the script above so that we do not just read the output from the console, but also save a text file as part of our lab notebook (works best if electronic)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "\tPicking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "\tAspirating 200.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "\tDispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "\tDropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 150.0 from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "\tPicking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "\tAspirating 150.0 uL from A1 of Corning 24 Well Plate 3.4 mL Flat on 2 at 1.0 speed\n",
      "\tDispensing 150.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "\tDropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "#%% Simulation\n",
    "\n",
    "from opentrons.simulate import simulate, format_runlog\n",
    "protocol_filename = 'Test_script.py' # TODO: change this for a new file\n",
    "protocol_file = open(protocol_filename)\n",
    "runlog = simulate(protocol_file, file_name='')\n",
    "print(format_runlog(runlog[0])) # Line modified compared to Opentrons Doc\n",
    "\n",
    "#%% Export simulated log file for documentation\n",
    "\n",
    "simulated_log_filename = protocol_filename.split('.py')[0] + '_log.txt'\n",
    "simulated_log = open(simulated_log_filename, 'w+', encoding = 'utf-8')\n",
    "simulated_log.write(format_runlog(runlog[0]))\n",
    "simulated_log.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can go back to the same folder and open \"Test_script_log.txt\" and we can see that the output is exactly the same as what is shown on the console.\n",
    "\n",
    "Advanced users can further add paths and folders so that the \"simulate.py\" file is placed inside a different folder.\n",
    "\n",
    "**We have now gone through the process for building a script and making it ready for execution!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# (Part II) Customizing the liquid transfer process\n",
    "\n",
    "Haivng a functional script is only the beginning. Very often we see unexpected behavior during the acutal pipetting steps and so many customizations are required before a protocol meets our demand. Fortuantely, the API provides multiple levels of control that we will find useful.\n",
    "\n",
    "## Customization on Transfers using Paramaters \n",
    "The following section corresponds to [\"Complex Commands: Parameters\"](https://docs.opentrons.com/v2/new_complex_commands.html#parameters) from the API docs.\n",
    "\n",
    "\n",
    "The `pipette.transfer()` function can take in a number of keyword arguments to change details during the pipetting step. There are many . Since this depends, we will only go over the ones which are more frequently called."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Set up\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single',\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### new_tip\n",
    "By default the `pipette.transfer()` function sets `new_tip` to `'once'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to C1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into C1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 200.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into D1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# Uses same tip for multiple transfer\n",
    "r_pipette.transfer(200, plate1.wells()[0:2], plate1.wells()[2:4]\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is helpful for distributions but will cause contamination in many-to-many transfers. It is better to set `new_tip` to `'always'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to C1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into C1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into D1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# Get a new tip every time\n",
    "r_pipette.transfer(200, plate1.wells()[0:2], plate1.wells()[2:4],\n",
    "                   new_tip='always'\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This, however, can be an issue when you are pipetting large volumes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 400.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# This will get a new tip even if we are pipetting the same sample.\n",
    "r_pipette.transfer(400, plate1.wells()[0], plate1.wells()[1],\n",
    "                   new_tip='always'\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### mix_before / mix_after\n",
    "Useful for protocols involving serial dilution.\n",
    "Note: check very carefully how it actually performs on the robot. Most of the time it does not do mixing properly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from F1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Mixing 3 times with a volume of 150.0 ul\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, plate1.wells()[0], plate1.wells()[1],\n",
    "                   mix_after=(3, 150) # mix for 3 cycles with volume of 150 µL \n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### disposal_volume\n",
    "If you need very accurate dispensing volume it is a good idea to aspirate an extra amount of volume so as to reduce residual volumes inside the tip.\n",
    "Note that the pipette discards the disposal volume at the trash though, so this will cause waste of the liquid sample."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from G1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Blowing out at A1 of Opentrons Fixed Trash on 12\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, plate1.wells()[0], plate1.wells()[1],\n",
    "                   disposal_volume=50\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Pipetting speed\n",
    "\n",
    "It is possible to change the plunger flow rate. The corresponding API is given at [\"Pipettes: Plunger Flow Rates\"](https://docs.opentrons.com/v2/new_pipette.html#plunger-flow-rates) from the API docs.\n",
    "\n",
    "Changing plunger flow rate on the pipette is global and should affect all pipetting steps. In most cases we wish to slow down or speed up a few specific pipetting steps within a protocol, so if we change the plunger flow rate on the pipette, we will have to reset the speed to default before moving onto the next step. This is therefore not recommended to do so this way. Rather, we recommend using the \"building block commands\" (see a later section for the example) which has the optional argument of `rate` that allows us to modify plunger flow rate locally within a single step of aspiration or dispense."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Well location\n",
    "\n",
    "The following section corresponds to [\"Labware: Specifying Position Within Wells\"](https://docs.opentrons.com/v2/new_labware.html#specifying-position-within-wells) from the API docs.  \n",
    "\n",
    "**Warning: read the warning in the docs on how collision would affect subsequent pipetteing**\n",
    "  \n",
    "Some pipetting would benefit from aspirating or dispensing liquid above or slightly below the liquid surface, for example, aspirating supernatant from a centrifuged sample. The OT-2 does not sense the liquid level, but it is possible to instruct the pipette to aspirate/dispense at location relative to the top/bottom of a well.\n",
    "\n",
    "This is done via calling an attribute of a well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=14.38, y=74.24, z=14.219999999999999), labware=A1 of Corning 96 Well Plate 360 µL Flat on 1)"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plate1.wells_by_name()['A1'].top() # top of the well"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=14.38, y=74.24, z=9.219999999999999), labware=A1 of Corning 96 Well Plate 360 µL Flat on 1)"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plate1.wells_by_name()['A1'].top(-5) # 5 mm below the top of the well"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Location(point=Point(x=14.38, y=74.24, z=13.549999999999999), labware=A1 of Corning 96 Well Plate 360 µL Flat on 1)"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "plate1.wells_by_name()['A1'].bottom(10) # 10 mm above the bottom of the well"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to B1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from H1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, plate1.wells()[0],\n",
    "                   plate1.wells()[1].top(-5) # location specified in a pipette.transfer() complex command\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that the output command does not show that information in the console, but it will be carried out by the robot as instructed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Achieving fine control through \"building block\" commands\n",
    "\n",
    "The following section corresponds to [\"Building Block Commands\"](https://docs.opentrons.com/v2/new_atomic_commands.html\n",
    ") from the API docs.\n",
    "\n",
    "\n",
    "It may appear that the `pipette.transfer()` function would suffice in many scenarios. In my personal experience, however, more often than not I would find unexpected behavior on the robot which jeopardize the entire experiment. For instance, mixing anything that is slighty more vicious than water, through capilliary action on the pipette tip, will lead to an incomplete dispense of liquid within each aspirate-dispense cycle. In the end, the tip used for transfer + mixing carried away a significant volume of liquid, and this could affect an experiment as simple as a serial dilution.\n",
    "\n",
    "We will thus introduce the building block commands. Once we master them we will have much better control over the fine details of our pipetting steps. And this is in fact, surprisingly easy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "plate2 = protocol.load_labware('corning_24_wellplate_3.4ml_flat', 2)\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 3)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single',\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider the following `pipette.transfer()` function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, plate1.wells_by_name()['A1'], plate1.wells_by_name()['A2'])\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we rewrite the above by the building block commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.pick_up_tip() # no argument required since the robot tracks tip usage for us\n",
    "r_pipette.aspirate(200, # aspirate volume\n",
    "                  plate1.wells_by_name()['A1'] # source well \n",
    "                  )\n",
    "r_pipette.dispense(volume=r_pipette.current_volume,\n",
    "                   location=plate1.wells_by_name()['A2'] # destination well\n",
    "                  )\n",
    "r_pipette.drop_tip()\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we compare the outputs from `pipette.transfer()` and the building block commands, we can see that there is virtually no difference in how the robot executes the function. The only difference is that the encapsulation line \"Transferring... ...\" is no longer present.\n",
    "\n",
    "Also note that we could have written `r_pipette.dispense(location=plate1.wells_by_name()['A2'])` directy instead.\n",
    "\n",
    "## Example 1: the blow_out=True issue\n",
    "\n",
    "So why should we bother using building block commands? Let's consider the following scenairo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Blowing out at A1 of Opentrons Fixed Trash on 12\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.transfer(200, plate1.wells_by_name()['A1'], plate1.wells_by_name()['A2'],\n",
    "                  blow_out = True # Note: key change here\n",
    "                  )\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As it turns out, Opentrons decided that, if you wish to expunge all liquid from the tip, those liquid will go to the trash instead of your destination well!\n",
    "\n",
    "As seasoned pipette users we all know it isn't how we usually do things. Alas, the logic in liquid handling automation is that you should always include a disposal volume during pipetting to increase pipetting accuracy. There will always be residual liquid sticking to the interior walls of the tip and we cannot afford to manually inspect them while the robot is running. So yes, there is a reason behind that.\n",
    "\n",
    "However, we sometimes work with precious samples and sometimes, we just have to sequeez out every bit of liquid from the tip into the well. Assuming we have to do so, we can rewrite the single `pipette.transfer()` function in the following way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Blowing out at A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.pick_up_tip() \n",
    "r_pipette.aspirate(200,\n",
    "                  plate1.wells_by_name()['A1']\n",
    "                  )\n",
    "r_pipette.dispense(volume=r_pipette.current_volume,\n",
    "                   location=plate1.wells_by_name()['A2']\n",
    "                  )\n",
    "r_pipette.blow_out(location=plate1.wells_by_name()['A2']) # if no argument, blow out at current position \n",
    "r_pipette.drop_tip()\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 2: Delay between aspiration and dispense\n",
    "In another instance, say we wish to wait 5 seconds after aspiration, to allow a slighlty viscous liquid to be properly aspirated before dispensing it elsewhere."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Delaying for 0 minutes and 5 seconds\n",
      "Dispensing 200.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "r_pipette.pick_up_tip() \n",
    "r_pipette.aspirate(200, plate1.wells_by_name()['A1'])\n",
    "\n",
    "protocol.delay(seconds=5) # additional line\n",
    "\n",
    "r_pipette.dispense(location=plate1.wells_by_name()['A2'])\n",
    "r_pipette.drop_tip()\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example 3: Mixing with customized speeds\n",
    "\n",
    "One final example here is a highly customized mixing process for a peculiar need. Say, we wish to mix a sample 3 times, but:\n",
    "1. The aspiration speed needs to be slower and the dispense speed needs to be faster.\n",
    "2. We need to ensure all liquid is blown out before aspirating for the next cycle in mixing.\n",
    "3. We want to dispense all liquid above the liquid level, not when the tip is still submerged inside the liquid.\n",
    "\n",
    "This might look daunting, but with the building block commands it is in fact quite straightforward:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from F1 of Opentrons 96 Tip Rack 300 µL on 3\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "well = plate1.wells_by_name()['A1']\n",
    "\n",
    "r_pipette.pick_up_tip() # use the same tip for mixing\n",
    "\n",
    "for i in range(3):\n",
    "\n",
    "    r_pipette.aspirate(150, # mix volume= 150 µL\n",
    "                       well,\n",
    "                       rate = .75 # slower rate for aspiration\n",
    "                      )\n",
    "\n",
    "    r_pipette.dispense(location=well.top(-5), # 2 mm from top of the well, ensures dispense above liquid level\n",
    "                       rate = 1.5 # faster rate for dispense\n",
    "                      )\n",
    "    \n",
    "r_pipette.drop_tip()\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also noteworthy that there is a `rate` argument that can modify pipetting speed, which is not applicable to the complex commands. The `rate` argument takes a float or integer coefficint and multiply the default speed (defined as rate=1) by that coefficient."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Writing reusable scripts\n",
    "\n",
    "One advantage in using the API is that we could easily expand a script by copying and pasting its content and making small changes. That said, in programming it is better to keep codes as general as required to minimize efforts in reusing a script.\n",
    "\n",
    "\n",
    "## Labware and pipetting loading\n",
    "For example, let's consider the scenarion that we are pipetting 200 µL of sample from one 96-well plate to another, say just from source well A1 to destination well A1, and we have to do it for 5 different destination plates. Using what we have written so far, we could write the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 2\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 3\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 3 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 4\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 4 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 5\n",
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 5 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 6\n",
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 6 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "source_plate = protocol.load_labware('corning_96_wellplate_360ul_flat', 1)\n",
    "dest_plate1 = protocol.load_labware('corning_96_wellplate_360ul_flat', 2)\n",
    "dest_plate2 = protocol.load_labware('corning_96_wellplate_360ul_flat', 3)\n",
    "dest_plate3 = protocol.load_labware('corning_96_wellplate_360ul_flat', 4)\n",
    "dest_plate4 = protocol.load_labware('corning_96_wellplate_360ul_flat', 5)\n",
    "dest_plate5 = protocol.load_labware('corning_96_wellplate_360ul_flat', 6)\n",
    "\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', 7)\n",
    "\n",
    "r_pipette = protocol.load_instrument(\n",
    "    'p300_single',\n",
    "    'right',\n",
    "    tip_racks=[tip_rack]\n",
    ")\n",
    "\n",
    "dest_plates = [dest_plate1, dest_plate2, dest_plate3, dest_plate4, dest_plate5]\n",
    "for dest_plate in dest_plates:\n",
    "    r_pipette.transfer(200,\n",
    "                       source_plate.wells_by_name()['A1'],\n",
    "                       dest_plate.wells_by_name()['A1']\n",
    "                      )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, we can easily imagine that this is unsustainable as we further scale up the experiment, or if we start a new experiment using different labware.\n",
    "\n",
    "We can restructure the code above to simplify labware loading and improve readability and reusability:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 2\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 2 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 3\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 3 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 4\n",
      "Picking up tip from D1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 4 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 200.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A1 of Corning 96 Well Plate 360 µL Flat on 5\n",
      "Picking up tip from E1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 200.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 200.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 5 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "#%% Deck layout and pipette setting\n",
    "deck_layout = {\n",
    "    1:'corning_96_wellplate_360ul_flat',\n",
    "    2:'corning_96_wellplate_360ul_flat',\n",
    "    3:'corning_96_wellplate_360ul_flat',\n",
    "    4:'corning_96_wellplate_360ul_flat',\n",
    "    5:'corning_96_wellplate_360ul_flat',\n",
    "    6:'corning_96_wellplate_360ul_flat'\n",
    "}\n",
    "\n",
    "l_pipette_name = ''\n",
    "r_pipette_name = 'p300_single'\n",
    "\n",
    "l_tip_rack_slots = []\n",
    "l_tiprack_name = ''\n",
    "\n",
    "r_tip_rack_slots = [7]\n",
    "r_tiprack_name = 'opentrons_96_tiprack_300ul'\n",
    "\n",
    "#%% Deck and instrument loading\n",
    "# DO NOT EDIT\n",
    "\n",
    "dlw = {} # dlw stands for deck_labware\n",
    "for slot, labware_item in deck_layout.items():\n",
    "    dlw.update({slot:protocol.load_labware(labware_item, slot)})\n",
    "\n",
    "if l_tip_rack_slots:\n",
    "    l_tip_racks = [protocol.load_labware(l_tiprack_name, slot) for slot in l_tip_rack_slots]\n",
    "\n",
    "if r_tip_rack_slots:\n",
    "    r_tip_racks = [protocol.load_labware(r_tiprack_name, slot) for slot in r_tip_rack_slots]\n",
    "\n",
    "if l_pipette_name:\n",
    "    l_pipette = protocol.load_instrument(r_pipette_name, mount = 'left', tip_racks = l_tip_racks)\n",
    "    \n",
    "if r_pipette_name:\n",
    "    r_pipette = protocol.load_instrument(r_pipette_name, mount = 'right', tip_racks = r_tip_racks)\n",
    "\n",
    "#%% Commands\n",
    "    \n",
    "for dest_slot in range(1, 6):\n",
    "    r_pipette.transfer(200,\n",
    "                       dlw[1].wells_by_name()['A1'],\n",
    "                       dlw[dest_slot].wells_by_name()['A1']\n",
    "                      )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that dictionary `deck_layout` now lists all the labware containers except tip racks that sit on the deck. It is easier to keep track of and modify labware items this way. The tip racks slots are seperated in another list variable because they need to associate with the pipette. By doing so, calling a labware item now done via `dlw[slot_number]` which is useful because labware items can now be looped by their slot numbers.\n",
    "\n",
    "Note that this is only a personal recommendation. In fact, I usually prefer commenting lines of unused pipettes out to avoid debugging problems. The key in structuring the script is to separate codes into *constant* and *variable* regions (just like an antibody) so as to minimize effort in tracking what needs to be changed every time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Reusable pipetting functions\n",
    "\n",
    "We have covered building block commands. If such building block commands are repeated over and over again it would be advantageous to wrap them inside function. We will reuse the example above on mixing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from F1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# The original script\n",
    "well = dlw[1].wells()[0]\n",
    "\n",
    "r_pipette.pick_up_tip() # use the same tip for mixing\n",
    "\n",
    "for i in range(3):\n",
    "\n",
    "    r_pipette.aspirate(150, # mix volume= 150 µL\n",
    "                       well,\n",
    "                       rate = .75 # slower rate for aspiration\n",
    "                      )\n",
    "\n",
    "    r_pipette.dispense(location=well.top(-5), # 2 mm from top of the well, ensures dispense above liquid level\n",
    "                       rate = 1.5 # faster rate for dispense\n",
    "                      )\n",
    "    \n",
    "r_pipette.drop_tip()\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Picking up tip from G1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Picking up tip from H1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Aspirating 150.0 uL from B1 of Corning 96 Well Plate 360 µL Flat on 1 at 0.75 speed\n",
      "Dispensing 150.0 uL into B1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.5 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "# A generalized function for mixing in a particular way\n",
    "\n",
    "def custom_mix(pipette, mix_vol, well):\n",
    "    pipette.pick_up_tip() # use the same tip for mixing\n",
    "    \n",
    "    for i in range(3):\n",
    "        pipette.aspirate(mix_vol, # mix volume= 150 µL\n",
    "                           well,\n",
    "                           rate = .75 # slower rate for aspiration\n",
    "                          )\n",
    "\n",
    "        pipette.dispense(location=well.top(-5), # 2 mm from top of the well, ensures dispense above liquid level\n",
    "                           rate = 1.5 # faster rate for dispense\n",
    "                          )\n",
    "\n",
    "    r_pipette.drop_tip()\n",
    "\n",
    "for i in range(2):\n",
    "    custom_mix(r_pipette, 150, dlw[1].wells()[i])\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that we have called the `custmom_mix()` function twiced using a for-loop. This would be more readable than having multiple layers of nested for-loops. Also, the object `pipette` is being used as an argument in the custom function, instead of being called directly for its own command.\n",
    "\n",
    "Note: In the final script to be executed, in theory these custom function can be placed inside or outside the `run()` function. Both should work, however, for beginners it is recommended that these functions be placed **after** labware items are loaded, since it is easy to miss variables that are defined outside the function."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Manual intergration with Excel\n",
    "\n",
    "Many biologists use Microsoft Excel for data analysis and for planning experiments. We introduce below one of the ways to harness the user-friendly tabular layout of Excel to generate Python parsable commands for the OT-2.\n",
    "\n",
    "First, we will create an Excel file that look like the following:\n",
    "\n",
    "|   | A      | B            | C           | D          | E         | F       |\n",
    "|---|--------|--------------|-------------|------------|-----------|---------|\n",
    "| 1 | volume | source_plate | source_well | dest_plate | dest_well | command |\n",
    "| 2 | 5      | 1            | A1          | 3          | D4        |         |\n",
    "| 3 | 10     | 2            | B2          | 4          | F5        |         |\n",
    "| 4 | 15     | 4            | C3          | 5          | G8        |         |\n",
    "\n",
    "Then, we will starting typing, under the command column, in cell `F1`, we will type:\n",
    "\n",
    "`=CONCAT(\"'\",B3, \"$\", C3, \"_\", D3, \"->\", E3, \"_\", F3,\"',\")`\n",
    "\n",
    "and then we will autofill the rest of the `command` column using the same formula.\n",
    "\n",
    "This will give us a table that looks like the following:\n",
    "\n",
    "|   | A      | B            | C           | D          | E         | F                |\n",
    "|---|--------|--------------|-------------|------------|-----------|------------------|\n",
    "| 1 | volume | source_plate | source_well | dest_plate | dest_well | command          |\n",
    "| 2 | 5      | 1            | A1          | 3          | D4        | '5\\$1_A1->3_D4',  |\n",
    "| 3 | 10     | 2            | B2          | 4          | F5        | '10\\$2_B2->4_F5', |\n",
    "| 4 | 15     | 4            | C3          | 5          | G8        | '15\\$4_C3->5_G8', |\n",
    "\n",
    "\n",
    "Reading this table above, we can see that we have condensed the minimal information for a pipetting step into single machine line, which remains readable by human, in the form of\n",
    "\n",
    "volume $ source slot _ source well -> dest slot _ dest well  \n",
    "  \n",
    "Each line can be presented as a string to Python within a Python list. We can then write a corresponding Python section to decode the information."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This cell is for preparation only\n",
    "\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "#%% Deck layout and pipette setting\n",
    "deck_layout = {\n",
    "    1:'corning_96_wellplate_360ul_flat',\n",
    "    2:'corning_96_wellplate_360ul_flat',\n",
    "    3:'corning_96_wellplate_360ul_flat',\n",
    "    4:'corning_96_wellplate_360ul_flat',\n",
    "    5:'corning_96_wellplate_360ul_flat'\n",
    "}\n",
    "\n",
    "l_pipette_name = ''\n",
    "r_pipette_name = 'p300_single'\n",
    "\n",
    "l_tip_rack_slots = []\n",
    "l_tiprack_name = ''\n",
    "\n",
    "r_tip_rack_slots = [7]\n",
    "r_tiprack_name = 'opentrons_96_tiprack_300ul'\n",
    "\n",
    "#%% Deck and instrument loading\n",
    "# DO NOT EDIT\n",
    "\n",
    "dlw = {} # dlw stands for deck_labware\n",
    "for slot, labware_item in deck_layout.items():\n",
    "    dlw.update({slot:protocol.load_labware(labware_item, slot)})\n",
    "\n",
    "if l_tip_rack_slots:\n",
    "    l_tip_racks = [protocol.load_labware(l_tiprack_name, slot) for slot in l_tip_rack_slots]\n",
    "\n",
    "if r_tip_rack_slots:\n",
    "    r_tip_racks = [protocol.load_labware(r_tiprack_name, slot) for slot in r_tip_rack_slots]\n",
    "\n",
    "if l_pipette_name:\n",
    "    l_pipette = protocol.load_instrument(r_pipette_name, mount = 'left', tip_racks = l_tip_racks)\n",
    "    \n",
    "if r_pipette_name:\n",
    "    r_pipette = protocol.load_instrument(r_pipette_name, mount = 'right', tip_racks = r_tip_racks)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 5.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to D4 of Corning 96 Well Plate 360 µL Flat on 3\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 5.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 5.0 uL into D4 of Corning 96 Well Plate 360 µL Flat on 3 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 10.0 from B2 of Corning 96 Well Plate 360 µL Flat on 2 to F5 of Corning 96 Well Plate 360 µL Flat on 4\n",
      "Picking up tip from B1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 10.0 uL from B2 of Corning 96 Well Plate 360 µL Flat on 2 at 1.0 speed\n",
      "Dispensing 10.0 uL into F5 of Corning 96 Well Plate 360 µL Flat on 4 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 15.0 from C3 of Corning 96 Well Plate 360 µL Flat on 4 to G8 of Corning 96 Well Plate 360 µL Flat on 5\n",
      "Picking up tip from C1 of Opentrons 96 Tip Rack 300 µL on 7\n",
      "Aspirating 15.0 uL from C3 of Corning 96 Well Plate 360 µL Flat on 4 at 1.0 speed\n",
      "Dispensing 15.0 uL into G8 of Corning 96 Well Plate 360 µL Flat on 5 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "#%% Transfer information\n",
    "\n",
    "transfer_commands = [\n",
    "\n",
    "    # The following contents are copied and pasted from the Excel spreadsheet\n",
    "    '5$1_A1->3_D4',\n",
    "    '10$2_B2->4_F5',\n",
    "    '15$4_C3->5_G8',\n",
    "\n",
    "]\n",
    "\n",
    "#%% Decoding the information and executing the commands\n",
    "\n",
    "for command in transfer_commands:\n",
    "    \n",
    "    volume = int(command.split('$')[0]) # extracted volume is a str, needs to convert to int\n",
    "    \n",
    "    transfer_path = command.split('$')[1] # breaks down '5$1_A1->3_D4' to '1_A1->3_D4'\n",
    "    \n",
    "    source = transfer_path.split('->')[0] # further breaks down '1_A1->3_D4' to '1_A1'\n",
    "    dest = transfer_path.split('->')[1] # further breaks down '1_A1->3_D4' to '3_D4'\n",
    "    \n",
    "    source_slot, source_well = source.split('_') # double assignment, source_slot='1' and source_well='A1'\n",
    "    dest_slot, dest_well = dest.split('_')\n",
    "    \n",
    "    # We used int for slots in \"deck_layout\", so we need to convert the type too\n",
    "    source_slot = int(source_slot)\n",
    "    dest_slot = int(dest_slot)\n",
    "\n",
    "    # Commands\n",
    "    r_pipette.transfer(volume,\n",
    "                       dlw[source_slot].wells_by_name()[source_well],\n",
    "                       dlw[dest_slot].wells_by_name()[dest_well]\n",
    "                      )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can further simplify the script, but the above version is a sufficiently good start to allow us to make good use of Excel to assist our experiment planning on an OT-2. The choices of delimiting characters can also be altered depeneding on our own need.\n",
    "\n",
    "It is possible to do .csv import in Python but it is not recommended, see Additional Remarks 2."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Additional remarks\n",
    "\n",
    "1. It is faster to use `pipette.transfer()` with list of well objects than looping a a single `pipette.transfer()` function multiple times. The difference in speed in unnoticeable on a PC but could mean 4-5 minutes of wait when API of a long protocol is compiled on a Pi-powered robot.\n",
    "\n",
    "The following example illustrates a comparison of the two methods, both trying to pipette 200 µL from well A1 to A7, B1 to B7, ... H6 to H12, for a total of 48 transfer steps.\n",
    "\n",
    "A single complex function processes multi-to-multi transfers much more efficiently, at the expense of losing fine-tuned control at the atomic movement level."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Run time comparison:\n",
      "Loop method: 0.843747615814209\n",
      "Well object method: 0.1515941619873047\n"
     ]
    }
   ],
   "source": [
    "# Set up\n",
    "import time\n",
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api('2.2')\n",
    "tip_rack = protocol.load_labware('opentrons_96_tiprack_300ul', location = '1')\n",
    "plate = protocol.load_labware('corning_96_wellplate_360ul_flat', location = '2')\n",
    "pipette = protocol.load_instrument('p300_single', mount = 'right', tip_racks = [tip_rack])\n",
    "print('Run time comparison:')\n",
    "\n",
    "# Method 1: List for looping pipette.transfer\n",
    "transfer_info = {x: x + 48 for x in range(0,48)}\n",
    "\n",
    "start_time = time.time()\n",
    "for source_index, dest_index in transfer_info.items():\n",
    "    pipette.transfer(200, plate.wells(source_index), plate.wells(dest_index))\n",
    "end_time = time.time()\n",
    "time_diff = end_time - start_time\n",
    "print('Loop method: ' + str(time_diff))\n",
    "\n",
    "# Method 2: Looping through a series of wells\n",
    "source_wells = plate.columns()[0:3]\n",
    "dest_wells = plate.columns()[4:7]\n",
    "start_time = time.time()\n",
    "pipette.transfer(200, source_wells, dest_wells)\n",
    "end_time = time.time()\n",
    "time_diff = end_time - start_time\n",
    "print('Well object method: ' + str(time_diff))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This difference looks insignificant to us, but we should remember that our script is executed on a Raspberry Pi inside the OT-2 and it will be a difference of minutes if our script gets longer and longer."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. It is possible to import csv files into our Python script. However, that requires a manual upload of the csv file to the storage space through the OT-2's [Jupyter Notebook terminal](https://docs.opentrons.com/v2/new_advanced_running.html#jupyter-notebook). Note that this is **not** the Jupyter Notebook of the computer that connects to the OT-2 but the Notebook that is executed from the Raspberry Pi inside the OT-2. [Further instructions](https://support.opentrons.com/en/articles/2519454-using-csv-input-data-in-python-protocol) for parsing the csv files are also provided by Opentrons.\n",
    "\n",
    "We strongly **discourage** doing so because it entails lab management problems. Labs with 10+ years of history often see their PCR machines storing many outdated protocols from alumni and eventually run of space. The Raspberry Pi inside the OT-2 has limited storage, and new members who do not wish to risk offending anyone will allow those old protocols/files to sit there forever and this will slowly chip away space for future OT-2 firmware upgrades. In contrast, the robot should only store the most recently uploaded protocol. Therefore, encoding all information inside an executable script is preferred."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. Labware objects issues:\n",
    "It is not important to have the exact labware name for a labware that we do not have. For example, our lab uses 96-well plates from Greiner Bio-One but we just use \"corning_96_wellplate_360ul_flat\" as the labware name and it works just fine. That is not always the case, however, especially when it comes to 96-well PCR plates. There are considerable differences in well heights across different manufacturers and so this needs to be tested case-by-case."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. When accessing wells on a labware, the direct access of wells without using a method (i.e., `plate['A1']`) is strongly discouraged. It might make it easier to read and save time in writing but when we start to build complex functions, it makes debugging much more difficult."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "5. It is possible to share tip rack between two pipettes and tip tracking will be fine if you are using single channel pipettes. However, that is a bad habit and **should be discouraged**. Consider the following scenario where we use a 8-channel pipette and a single channel pipette together."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transferring 15.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A1 of Opentrons 96 Tip Rack 300 µL on 2\n",
      "Aspirating 15.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 15.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n",
      "Transferring 15.0 from A1 of Corning 96 Well Plate 360 µL Flat on 1 to A2 of Corning 96 Well Plate 360 µL Flat on 1\n",
      "Picking up tip from A2 of Opentrons 96 Tip Rack 300 µL on 2\n",
      "Aspirating 15.0 uL from A1 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dispensing 15.0 uL into A2 of Corning 96 Well Plate 360 µL Flat on 1 at 1.0 speed\n",
      "Dropping tip into A1 of Opentrons Fixed Trash on 12\n"
     ]
    }
   ],
   "source": [
    "from opentrons import simulate\n",
    "protocol = simulate.get_protocol_api(version = '2.4')\n",
    "\n",
    "#%% Deck layout and pipette setting\n",
    "deck_layout = {\n",
    "    1:'corning_96_wellplate_360ul_flat'\n",
    "}\n",
    "\n",
    "l_pipette_name = 'p300_single'\n",
    "r_pipette_name = 'p300_multi'\n",
    "\n",
    "shared_tip_rack_slots = [2]\n",
    "shared_tiprack_name = 'opentrons_96_tiprack_300ul'\n",
    "\n",
    "dlw = {} # dlw stands for deck_labware\n",
    "for slot, labware_item in deck_layout.items():\n",
    "    dlw.update({slot:protocol.load_labware(labware_item, slot)})\n",
    "\n",
    "if shared_tip_rack_slots:\n",
    "    shared_tip_racks = [protocol.load_labware(shared_tiprack_name, slot) for slot in shared_tip_rack_slots]\n",
    "\n",
    "if l_pipette_name:\n",
    "    l_pipette = protocol.load_instrument(r_pipette_name, mount = 'left', tip_racks = shared_tip_racks)\n",
    "    \n",
    "if r_pipette_name:\n",
    "    r_pipette = protocol.load_instrument(r_pipette_name, mount = 'right', tip_racks = shared_tip_racks)\n",
    "    \n",
    "# Commands\n",
    "l_pipette.transfer(volume,\n",
    "                   dlw[1].wells_by_name()['A1'],\n",
    "                   dlw[1].wells_by_name()['A2']\n",
    "                  )\n",
    "\n",
    "r_pipette.transfer(volume,\n",
    "                   dlw[1].wells_by_name()['A1'],\n",
    "                   dlw[1].wells_by_name()['A2']\n",
    "                  )\n",
    "\n",
    "print(*protocol.commands(), sep = '\\n')\n",
    "protocol.clear_commands()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that left P300S took a tip from A1 in the tip rack but then the right P300M took tips from B1-H1 + (missing tip). At this point the API is not smart enough to tell how to pick up tips. This can be overcome using `pipette.pick_up_tip()` but the risk is not worth the tips being saved. It is better to always **assign separate tip racks** to the two pipettes."
   ]
  }
 ],
 "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.7"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": true,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "336.4px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}