notebooks/getting_started.ipynb

{
 "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
}