tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "a31ad33c-2bcb-4fb4-bb8d-9c0f790cdd16",
   "metadata": {},
   "outputs": [],
   "source": [
    "from alhambra_mixes import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0be0c2b1-2cbf-4559-8408-6fece2066b34",
   "metadata": {},
   "source": [
    "# Concepts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8dccdf4-0c8f-4b37-99f7-6a06c1b71bf7",
   "metadata": {},
   "source": [
    "Mixes ..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2e49a23f-a0d9-469b-b0f5-e0fe6e0b0a0c",
   "metadata": {},
   "source": [
    "## Components"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3539d646-cf10-4244-a95c-78cf896d7b16",
   "metadata": {},
   "source": [
    "Components ..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc4c5667-9bea-42f6-920b-5acb080c30cb",
   "metadata": {},
   "source": [
    "The base `Component` class is meant to usable generically.  For example, we might have a solution of MgCl₂ that we'd like to use to make a Mg-added buffer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "2bdfe6f1-d709-42fd-a944-1e719f429580",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Component(name='MgCl₂', concentration=<Quantity(1, 'molar')>, plate='', well=None)\n"
     ]
    }
   ],
   "source": [
    "mg = Component(\"MgCl₂\", \"1 M\")\n",
    "print(mg)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d3e7494-e210-4cac-8b5e-504ef33a71d0",
   "metadata": {},
   "source": [
    "Like many components in mixes, the concentration is easiest to enter as a string.  mixes uses the [pint](https://github.com/hgrecco/pint) library to handle units, and Python's [decimal](FIXME) library to avoid imprecision in calculations.  It does this as transparently as possible: you can enter most values with units as either a string, or a pint Quantity, and they will be converted correctly.  You can use `Q_` as a shorthand to create a Quantity from a string, or a number for the value and string for the units.  The input should be quite flexible, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "343c443b-ae8c-42b2-9ba3-f3673a5509e2",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Q_(\"5 µM\") == Q_(5, \"µM\") == Q_(\"5 micromolar\") == Q_(\"5 pmol / microliter\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15dd73ef-f553-4de6-8ade-7ca69c5136eb",
   "metadata": {},
   "source": [
    "In addition to having a name and a concentration, a component can have a location (currently using the `plate` property), and, if the location is a plate name, can also be given a `well`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f5d6d50-c791-484f-87bc-8edcf98d3442",
   "metadata": {},
   "source": [
    "## Actions and Mixes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45b5035e-f517-45d0-a370-03c9a492ef38",
   "metadata": {},
   "source": [
    "mixes combines Components into Mixes through Actions.  Actions specify what we'd like to do with a component, or a list of components, when we add them to a mix.  For example, we might want to make a buffer stock with 125 mM of MgCl₂ in it, in which case we could use the `FixedConcentration` action, which adds a single component at a fixed target concentration:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "4ee1554a-2e9e-420f-88e5-744786529a4c",
   "metadata": {},
   "outputs": [],
   "source": [
    "add_mg = FixedConcentration(mg, \"125 mM\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e75ce8f-e63e-4608-924e-631070dc08eb",
   "metadata": {},
   "source": [
    "A `Mix`, then, is a list of these actions, together with some overall properties, like a name or "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "b6f72a8c-c952-493b-96c7-cebacaff5dc8",
   "metadata": {},
   "outputs": [],
   "source": [
    "mg_buffer = Mix([add_mg], \"10× Mg\", fixed_total_volume=\"1 mL\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "eca33bd6-33d9-4c1b-bfb7-de6fd35a3b44",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Table: Mix: 10× Mg, Conc: 125.00 mM, Total Vol: 1.00 ml\n",
       "\n",
       "| Component   | [Src]   | [Dest]      | #   | Ea Tx Vol   | Tot Tx Vol   | Location   | Note   |\n",
       "|:------------|:--------|:------------|:----|:------------|:-------------|:-----------|:-------|\n",
       "| MgCl₂       | 1.00 M  | 125.00 mM   |     | 125.00 µl   | 125.00 µl    |            |        |\n",
       "| Buffer      |         |             |     | 875.00 µl   | 875.00 µl    |            |        |\n",
       "| *Total:*    |         | *125.00 mM* | *2* |             | *1.00 ml*    |            |        |"
      ],
      "text/plain": [
       "Mix(\"10× Mg\", 1 actions)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mg_buffer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31a0b56d-c002-4798-a9e3-71a60383ad8b",
   "metadata": {},
   "source": [
    "As we will see later, a `Mix` itself can also be a component in other mixes."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d80fe499-f4cc-4928-8c72-0393f6357958",
   "metadata": {},
   "source": [
    "# Strands and References"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19ec5335-60a9-4093-9539-2429f2a63bc5",
   "metadata": {},
   "source": [
    "A `Strand` is a type of component that also keeps track of a sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "2b5ffc8d-5b65-496f-9b00-6eee1ff28fc9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Strand(name='S1', concentration=<Quantity(100, 'micromolar')>, plate='', well=None, sequence='AGAAT')"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Strand(\"S1\", concentration=\"100 µM\", sequence=\"AGAAT\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "443d471a-9f47-4a91-9608-2ce5b627f294",
   "metadata": {},
   "source": [
    "Specifying all properties of every component in code would be time consuming and error prone.  Instead, we can specify the components without all properties, or even with just a name, and then use a `Reference` to add information to them.  Here, we'll create a simple reference as (fake) csv file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "ea501c73-6f31-4625-badd-a06df00c0dd9",
   "metadata": {},
   "outputs": [],
   "source": [
    "import io\n",
    "\n",
    "# Columns are \"Name\", \"Plate\", \"Well\", \"Concentration (nM)\", \"Sequence\"\n",
    "csv_file = io.StringIO(\n",
    "    \"\"\"\n",
    "Name,Plate,Well,\"Concentration (nM)\",Sequence\n",
    "S1,plate1,A2,100000,AGAAT\n",
    "S2,plate1,A3,125000,GTTCT\n",
    "S3,plate1,A4,125000,GTTCT\n",
    "S4,plate1,A5,125000,GTTCT\n",
    "S5,plate1,B1,125000,GTTCT\n",
    "S6,plate1,B2,125000,GTTCT\n",
    "\"\"\"\n",
    ")\n",
    "\n",
    "ref = Reference.from_csv(csv_file)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6181e33d-827a-4649-827c-4ae45eb851b1",
   "metadata": {},
   "source": [
    "Now, we can use `.with_reference` to add information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "60cf0b27-b331-4aa1-8143-ea447f88aa09",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Strand(name='S2', concentration=<Quantity(NaN, 'nanomolar')>, plate='', well=None, sequence=None)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Strand(\"S2\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "7540118c-99a4-45e3-8176-c6331d4fc7bc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Strand(name='S2', concentration=<Quantity(125.000000, 'micromolar')>, plate='plate1', well=WellPos(\"A3\"), sequence='GTTCT')"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Strand(\"S2\").with_reference(ref)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "777fc940-6648-4cbd-90dc-9718ce7a72c3",
   "metadata": {},
   "source": [
    "## Larger mixes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "adef04c0-e8c5-499c-ab63-0cfad278fbb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "ref = ref"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "29ac806d-7aab-460b-a10f-3b6a7a296cf9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Table: Mix: strand mix A, Conc: 38.46 µM, Total Vol: 6.50 µl\n",
       "\n",
       "| Component   | [Src]     | [Dest]     | #   | Ea Tx Vol   | Tot Tx Vol   | Location           | Note   |\n",
       "|:------------|:----------|:-----------|:----|:------------|:-------------|:-------------------|:-------|\n",
       "| S2, S3      | 125.00 µM | 38.46 µM   | 2   | 2.00 µl     | 4.00 µl      | **plate1: A3**, A4 |        |\n",
       "| S1          | 100.00 µM | 38.46 µM   |     | 2.50 µl     | 2.50 µl      | plate1: A2         |        |\n",
       "| *Total:*    |           | *38.46 µM* | *3* |             | *6.50 µl*    |                    |        |"
      ],
      "text/plain": [
       "Mix(\"strand mix A\", 1 actions)"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "strandmix1 = Mix(\n",
    "    [\n",
    "        MultiFixedVolume(\n",
    "            components=[Strand(f\"S{x}\") for x in range(1, 4)],\n",
    "            fixed_volume=\"2 µL\",\n",
    "            equal_conc=\"min_volume\",\n",
    "        )\n",
    "    ],\n",
    "    \"strand mix A\",\n",
    ").with_reference(ref)\n",
    "strandmix1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "29ff1d08-8812-4917-8c46-dfe6cff9d99e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Table: Mix: strand mix B, Conc: 1.00 µM, Total Vol: 100.00 µl\n",
       "\n",
       "| Component   | [Src]     | [Dest]    | #   | Ea Tx Vol   | Tot Tx Vol   | Location         | Note   |\n",
       "|:------------|:----------|:----------|:----|:------------|:-------------|:-----------------|:-------|\n",
       "| S4,         | 125.00 µM | 1.00 µM   | 3   | 800.00 nl   | 2.40 µl      | **plate1: A5**,  |        |\n",
       "| S5, S6      |           |           |     |             |              | **B1**, B2       |        |\n",
       "| Buffer      |           |           |     | 97.60 µl    | 97.60 µl     |                  |        |\n",
       "| *Total:*    |           | *1.00 µM* | *4* |             | *100.00 µl*  |                  |        |"
      ],
      "text/plain": [
       "Mix(\"strand mix B\", 1 actions)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "strandmix2 = Mix(\n",
    "    [\n",
    "        MultiFixedConcentration(\n",
    "            components=[Strand(f\"S{x}\") for x in range(4, 7)],\n",
    "            fixed_concentration=\"1 µM\",\n",
    "        )\n",
    "    ],\n",
    "    \"strand mix B\",\n",
    "    fixed_total_volume=\"100 µL\",\n",
    ").with_reference(ref)\n",
    "strandmix2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b435da5a-570f-40e1-b7d0-a62ccb6ac982",
   "metadata": {},
   "source": [
    "With strands on plates..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "2cb6e775-4096-4950-8531-46b8865217de",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Table: Mix: Sample 1, Conc: 500.00 nM, Total Vol: 100.00 µl\n",
       "\n",
       "| Component    | [Src]     | [Dest]      | #   | Ea Tx Vol   | Tot Tx Vol   | Location   | Note   |\n",
       "|:-------------|:----------|:------------|:----|:------------|:-------------|:-----------|:-------|\n",
       "| strand mix A | 38.46 µM  | 500.00 nM   |     | 1.30 µl     | 1.30 µl      |            |        |\n",
       "| strand mix B | 1.00 µM   | 100.00 nM   |     | 10.00 µl    | 10.00 µl     |            |        |\n",
       "| 10× Mg       | 125.00 mM | 12.50 mM    |     | 10.00 µl    | 10.00 µl     |            |        |\n",
       "| Buffer       |           |             |     | 78.70 µl    | 78.70 µl     |            |        |\n",
       "| *Total:*     |           | *500.00 nM* | *4* |             | *100.00 µl*  |            |        |"
      ],
      "text/plain": [
       "Mix(\"Sample 1\", 3 actions)"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sample1 = Mix(\n",
    "    [\n",
    "        FixedConcentration(strandmix1, \"500 nM\"),\n",
    "        FixedConcentration(strandmix2, \"100 nM\"),\n",
    "        FixedConcentration(mg_buffer, \"12.5 mM\"),\n",
    "    ],\n",
    "    name=\"Sample 1\",\n",
    "    fixed_total_volume=\"100 µL\",\n",
    ")\n",
    "sample1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c0463bb7-f51a-44ae-8b86-c2dce21a0238",
   "metadata": {},
   "source": [
    "In addition to seeing the series of recipes above..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "bbe213d0-bc7c-44a7-b75f-7f10b7d48800",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>concentration_nM</th>\n",
       "      <th>component</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>MgCl₂</th>\n",
       "      <td>12500000.0</td>\n",
       "      <td>Component(name='MgCl₂', concentration=&lt;Quantit...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S1</th>\n",
       "      <td>500.000000</td>\n",
       "      <td>Strand(name='S1', concentration=&lt;Quantity(100....</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S2</th>\n",
       "      <td>500.000000</td>\n",
       "      <td>Strand(name='S2', concentration=&lt;Quantity(125....</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S3</th>\n",
       "      <td>500.000000</td>\n",
       "      <td>Strand(name='S3', concentration=&lt;Quantity(125....</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S4</th>\n",
       "      <td>100.000000</td>\n",
       "      <td>Strand(name='S4', concentration=&lt;Quantity(125....</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S5</th>\n",
       "      <td>100.000000</td>\n",
       "      <td>Strand(name='S5', concentration=&lt;Quantity(125....</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S6</th>\n",
       "      <td>100.000000</td>\n",
       "      <td>Strand(name='S6', concentration=&lt;Quantity(125....</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      concentration_nM                                          component\n",
       "name                                                                     \n",
       "MgCl₂       12500000.0  Component(name='MgCl₂', concentration=<Quantit...\n",
       "S1          500.000000  Strand(name='S1', concentration=<Quantity(100....\n",
       "S2          500.000000  Strand(name='S2', concentration=<Quantity(125....\n",
       "S3          500.000000  Strand(name='S3', concentration=<Quantity(125....\n",
       "S4          100.000000  Strand(name='S4', concentration=<Quantity(125....\n",
       "S5          100.000000  Strand(name='S5', concentration=<Quantity(125....\n",
       "S6          100.000000  Strand(name='S6', concentration=<Quantity(125...."
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sample1.all_components()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e274e36b-f596-4574-a7c3-1a0f06aacdcd",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.5 64-bit",
   "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.10.5"
  },
  "vscode": {
   "interpreter": {
    "hash": "e7370f93d1d0cde622a1f8e1c04877d8463912d04d973331ad4851f04de6915a"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}