updated docs; intro and viz

notebooks/getting_started.ipynb

@@ -0,0 +1,286 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting started"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To start using the package, you would need: a **model** and an **expression dataset** to integrate with the model. Let's start by exploring how to create an expression dataset."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Generating an expression profile dataset"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To integrate genomics or proteomics data in the model, we need to create a `driven.ExpressionProfile` instance which will handle all the necessary requirements for the purpose. The `ExpressionProfile` class takes a `numpy.ndarray` for the expression data and list-like structures for the **identifiers** (genes/proteins) and **conditons** (media, time, etc.). For this example though, we will build a toy dataset from [doi: 10.3389/fphys.2012.00299](https://doi.org/10.3389/fphys.2012.00299):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "source": [
+    "import numpy as np\n",
+    "from driven import ExpressionProfile\n",
+    "\n",
+    "genes = [\"Gene2\", \"Gene3\", \"Gene6\", \"Gene7\"]\n",
+    "conditions = [\"Exp#1\", \"Exp#2\", \"Exp#3\"]\n",
+    "expression = np.array(([0.17, 0.20, 0.93],\n",
+    "                       [0.36, 0.83, 0.77],\n",
+    "                       [0.87, 0.65, 0.07],\n",
+    "                       [0.55, 0.49, 0.52]))\n",
+    "\n",
+    "model_expression = ExpressionProfile(genes, conditions, expression)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "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>Exp#1</th>\n",
+       "      <th>Exp#2</th>\n",
+       "      <th>Exp#3</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>Gene2</th>\n",
+       "      <td>0.17</td>\n",
+       "      <td>0.20</td>\n",
+       "      <td>0.93</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>Gene3</th>\n",
+       "      <td>0.36</td>\n",
+       "      <td>0.83</td>\n",
+       "      <td>0.77</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>Gene6</th>\n",
+       "      <td>0.87</td>\n",
+       "      <td>0.65</td>\n",
+       "      <td>0.07</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>Gene7</th>\n",
+       "      <td>0.55</td>\n",
+       "      <td>0.49</td>\n",
+       "      <td>0.52</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "<driven.data_sets.expression_profile.ExpressionProfile at 0x1108066a0>"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model_expression"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Generating a model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We use [cobrapy](https://github.com/opencobra/cobrapy) to build or load a new model. If you are new to cobrapy, it is recommended to check its [documentation](https://cobrapy.readthedocs.io). Now that we have an expression dataset, we generate the required model like so:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "source": [
+    "import cobra\n",
+    "\n",
+    "model = cobra.Model(\"Blazier et al 2012\")\n",
+    "r_1 = cobra.Reaction(\"R1\")\n",
+    "r_2 = cobra.Reaction(\"R2\")\n",
+    "r_3 = cobra.Reaction(\"R3\")\n",
+    "r_4 = cobra.Reaction(\"R4\")\n",
+    "r_5 = cobra.Reaction(\"R5\")\n",
+    "r_6 = cobra.Reaction(\"R6\")\n",
+    "r_7 = cobra.Reaction(\"R7\")\n",
+    "r_8 = cobra.Reaction(\"R8\")\n",
+    "\n",
+    "model.add_reactions([r_1, r_2, r_3, r_4, r_5, r_6, r_7, r_8])\n",
+    "\n",
+    "r_1.reaction = \"M1_e -> M1\"\n",
+    "r_2.reaction = \"M1 -> M2\"\n",
+    "r_3.reaction = \"M2 -> M3\"\n",
+    "r_4.reaction = \"M3 ->\"\n",
+    "r_5.reaction = \"M4_e -> M4\"\n",
+    "r_6.reaction = \"M4 -> M5\"\n",
+    "r_7.reaction = \"M5 <-> M2\"\n",
+    "r_8.reaction = \"M5 ->\"\n",
+    "\n",
+    "r_2.gene_reaction_rule = \"Gene2\"\n",
+    "r_3.gene_reaction_rule = \"Gene3\"\n",
+    "r_6.gene_reaction_rule = \"Gene6\"\n",
+    "r_7.gene_reaction_rule = \"Gene7\"\n",
+    "\n",
+    "EX_M1_e = model.add_boundary(model.metabolites.M1_e, lb=-10.0)\n",
+    "EX_M4_e = model.add_boundary(model.metabolites.M4_e, lb=-10.0)\n",
+    "\n",
+    "model.objective = r_4"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "\n",
+       "        <table>\n",
+       "            <tr>\n",
+       "                <td><strong>Name</strong></td>\n",
+       "                <td>Blazier et al 2012</td>\n",
+       "            </tr><tr>\n",
+       "                <td><strong>Memory address</strong></td>\n",
+       "                <td>0x011a596c88</td>\n",
+       "            </tr><tr>\n",
+       "                <td><strong>Number of metabolites</strong></td>\n",
+       "                <td>7</td>\n",
+       "            </tr><tr>\n",
+       "                <td><strong>Number of reactions</strong></td>\n",
+       "                <td>10</td>\n",
+       "            </tr><tr>\n",
+       "                <td><strong>Objective expression</strong></td>\n",
+       "                <td>1.0*R4 - 1.0*R4_reverse_8717c</td>\n",
+       "            </tr><tr>\n",
+       "                <td><strong>Compartments</strong></td>\n",
+       "                <td></td>\n",
+       "            </tr>\n",
+       "          </table>"
+      ],
+      "text/plain": [
+       "<Model Blazier et al 2012 at 0x11a596c88>"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using the data with the model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's perform a trivial computation to see how we can integrate the components:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'R2': 0.200000000000000,\n",
+       " 'R3': 0.830000000000000,\n",
+       " 'R6': 0.650000000000000,\n",
+       " 'R7': 0.490000000000000}"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "reaction_data = model_expression.to_reaction_dict(condition=\"Exp#2\", model=model)\n",
+    "reaction_data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here, we see how we are able to map the gene expression data to the respective reaction by using the GPR (Gene-Protein-Reaction) associations."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "driven",
+   "language": "python",
+   "name": "driven"
+  },
+  "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.6.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}