docs/tutorials/enzyme_modules.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Enzyme Modules\n",
    "\n",
    "An \"enzyme module\" is defined as a mechanistic description of a reaction consisting of mass action rate laws for all known reaction steps <cite data-cite=\"DZK+16\">(Du et al., 2016)</cite>. In **MASSpy**, enzyme modules are represented by the `EnzymeModule` object.\n",
    "\n",
    "To demonstrate the utility of an `EnzymeModule` object and how it aids in constructing mechanistic models of enzyme behavior, an `EnzymeModule` of hexokinase$^{1, 2}$ is constructed and then merged with a model of glycolysis$^{3}$ for verification."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Constructing Enzyme Modules\n",
    "\n",
    "In order to construct the `EnzymeModule` of hexokinase, the following information is necessary:\n",
    "\n",
    "1. The enzyme is a monomer.\n",
    "2. The enzyme binding of substrates follows a random sequential mechanism.\n",
    "3. The enzyme experiences product inhibtion and is competitively inhibited by 23DPG when complexed with D-glucose.\n",
    "\n",
    "Total HEX1 Concentration$^2$: $\\text{[HEX1]}_{total} = 24 nM = 0.000024 mM$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:34:56.836681Z",
     "iopub.status.busy": "2020-10-20T20:34:56.835736Z",
     "iopub.status.idle": "2020-10-20T20:35:00.176995Z",
     "shell.execute_reply": "2020-10-20T20:35:00.177452Z"
    }
   },
   "outputs": [],
   "source": [
    "from operator import attrgetter\n",
    "\n",
    "from mass import MassMetabolite\n",
    "from mass.enzyme_modules import EnzymeModule\n",
    "from mass.test import create_test_model\n",
    "\n",
    "# Load the glycolysis and hemoglobin models, then merge them\n",
    "glycolysis = create_test_model(\"Glycolysis\")\n",
    "hemoglobin = create_test_model(\"Hemoglobin\")\n",
    "glyc_hb = glycolysis.merge(hemoglobin, inplace=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EnzymeModule` is a subclass of the `MassModel`, meaning that it inherits the methods and behaviors of the `MassModel` object. \n",
    "Like a `MassModel`, an `EnzymeModule` object requires a unique identifier in order to be created. Optionally, the `name` and `subsystem` attributes are set during initialization."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.182688Z",
     "iopub.status.busy": "2020-10-20T20:35:00.182039Z",
     "iopub.status.idle": "2020-10-20T20:35:00.184516Z",
     "shell.execute_reply": "2020-10-20T20:35:00.185012Z"
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "HEX1 = EnzymeModule(\"HEX1\", name=\"Hexokinase (D-glucose:ATP)\",\n",
    "                    subsystem=\"Glycolysis\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining the enzyme ligands\n",
    "\n",
    "The ligands that interact with the enzyme (e.g. as the substrates, activators, and inhibitors) are created as `MassMetabolite` objects and added to the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.192210Z",
     "iopub.status.busy": "2020-10-20T20:35:00.191541Z",
     "iopub.status.idle": "2020-10-20T20:35:00.193761Z",
     "shell.execute_reply": "2020-10-20T20:35:00.194204Z"
    }
   },
   "outputs": [],
   "source": [
    "glc__D_c = MassMetabolite(\n",
    "    \"glc__D_c\",\n",
    "    name=\"D-Glucose\",\n",
    "    formula=\"C6H12O6\",\n",
    "    charge=0,\n",
    "    compartment=\"c\")\n",
    "g6p_c = MassMetabolite(\n",
    "    \"g6p_c\",\n",
    "    name=\"D-Glucose 6-phosphate\",\n",
    "    formula=\"C6H11O9P\",\n",
    "    charge=-2,\n",
    "    compartment=\"c\")\n",
    "atp_c = MassMetabolite(\n",
    "    \"atp_c\",\n",
    "    name=\"ATP\",\n",
    "    formula=\"C10H12N5O13P3\",\n",
    "    charge=-4,\n",
    "    compartment=\"c\")\n",
    "adp_c = MassMetabolite(\n",
    "    \"adp_c\",\n",
    "    name=\"ADP\",\n",
    "    formula=\"C10H12N5O10P2\",\n",
    "    charge=-3,\n",
    "    compartment=\"c\")\n",
    "_23dpg_c = MassMetabolite(\n",
    "    \"_23dpg_c\", \n",
    "    name=\"2,3-Disphospho-D-glycerate\", \n",
    "    formula=\"C3H3O10P2\",\n",
    "    charge=-5,\n",
    "    compartment=\"c\")\n",
    "h_c = MassMetabolite(\n",
    "    \"h_c\",\n",
    "    name=\"H+\",\n",
    "    formula=\"H\",\n",
    "    charge=1,\n",
    "    compartment=\"c\")\n",
    "\n",
    "HEX1.add_metabolites([glc__D_c, g6p_c, atp_c, adp_c, _23dpg_c, h_c])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once added to the `EnzymeModule`, ligands can be accessed using the `enzyme_module_ligands` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.200571Z",
     "iopub.status.busy": "2020-10-20T20:35:00.199796Z",
     "iopub.status.idle": "2020-10-20T20:35:00.203633Z",
     "shell.execute_reply": "2020-10-20T20:35:00.204079Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<MassMetabolite glc__D_c at 0x7ff42b809390>,\n",
       " <MassMetabolite g6p_c at 0x7ff42b809350>,\n",
       " <MassMetabolite atp_c at 0x7ff42b8093d0>,\n",
       " <MassMetabolite adp_c at 0x7ff42b809410>,\n",
       " <MassMetabolite _23dpg_c at 0x7ff42b809490>,\n",
       " <MassMetabolite h_c at 0x7ff42b8094d0>]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "HEX1.enzyme_module_ligands"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To keep track of the roles played by various ligands in the module, the `enzyme_module_ligands_categorized` attribute is set. The attribute takes a `dict`, with categories as keys and relevant `MassMetabolite` objects as values. Note that an object can be a part of multiple categories."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.209218Z",
     "iopub.status.busy": "2020-10-20T20:35:00.208422Z",
     "iopub.status.idle": "2020-10-20T20:35:00.211208Z",
     "shell.execute_reply": "2020-10-20T20:35:00.211650Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<Group substrates at 0x7ff42b809ad0>,\n",
       " <Group cofactors at 0x7ff42b809bd0>,\n",
       " <Group inhibitors at 0x7ff42b809c50>,\n",
       " <Group products at 0x7ff42b809cd0>]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "HEX1.enzyme_module_ligands_categorized =  {\n",
    "    \"substrates\": glc__D_c,\n",
    "    \"cofactors\": atp_c,\n",
    "    \"inhibitors\": _23dpg_c,\n",
    "    \"products\": [adp_c, g6p_c, h_c]}\n",
    "HEX1.enzyme_module_ligands_categorized"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For each category, a `cobra.Group` is created containing the relevant objects. Once set, the attribute returns a `cobra.DictList` that contains the categorized groups. The groups and their members are printed as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.216465Z",
     "iopub.status.busy": "2020-10-20T20:35:00.215752Z",
     "iopub.status.idle": "2020-10-20T20:35:00.218536Z",
     "shell.execute_reply": "2020-10-20T20:35:00.218987Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "substrates: ['glc__D_c']\n",
      "cofactors: ['atp_c']\n",
      "inhibitors: ['_23dpg_c']\n",
      "products: ['adp_c', 'g6p_c', 'h_c']\n"
     ]
    }
   ],
   "source": [
    "for group in HEX1.enzyme_module_ligands_categorized:\n",
    "    print(\"{0}: {1}\".format(\n",
    "        group.id, str(sorted([m.id for m in group.members]))))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining the enzyme module forms\n",
    "\n",
    "After adding `MassMetabolite` objects of ligands to the model, the various forms of the enzyme must be defined. These forms are represented by `EnzymeModuleForm` objects. \n",
    "\n",
    "The `EnzymeModuleForm` object inherits from the `MassMetabolite` and is treated like any other metabolite in the model. However, the `EnzymeModuleForm` object contains the additional `bound_metabolites` attribute to assist in tracking metabolites bound to the enzyme form. \n",
    "\n",
    "The `EnzymeModule.make_enzyme_module_form()` method allows for the creation of an `EnzymeModuleForm` object while assigning categories for the  `EnzymeModuleForm` in the process. Using `make_enzyme_module_form()` also adds the species to the module upon creation, accessible via the `EnzymeModule.enzyme_module_forms` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.230139Z",
     "iopub.status.busy": "2020-10-20T20:35:00.229241Z",
     "iopub.status.idle": "2020-10-20T20:35:00.232461Z",
     "shell.execute_reply": "2020-10-20T20:35:00.232965Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<EnzymeModuleForm hex1_c at 0x7ff42b82e750>,\n",
       " <EnzymeModuleForm hex1_A_c at 0x7ff42b82e790>,\n",
       " <EnzymeModuleForm hex1_G_c at 0x7ff42b82e850>,\n",
       " <EnzymeModuleForm hex1_AG_c at 0x7ff42b82e710>,\n",
       " <EnzymeModuleForm hex1_G_CI_c at 0x7ff42b82eb50>,\n",
       " <EnzymeModuleForm hex1_A_PI_c at 0x7ff42b82ee10>,\n",
       " <EnzymeModuleForm hex1_G_PI_c at 0x7ff42b82ed10>]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hex1_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_c\",\n",
    "    name=\"automatic\",\n",
    "    categories=\"Active\",\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_A_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_A_c\",  # A stands complexted with ATP\n",
    "    name=\"automatic\",\n",
    "    categories=\"Active\",\n",
    "    bound_metabolites={atp_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_G_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_G_c\",  # G stands for complexed with Glucose\n",
    "    name=\"automatic\",\n",
    "    categories=\"Active\",\n",
    "    bound_metabolites={glc__D_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_AG_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_AG_c\",\n",
    "    name=\"automatic\",\n",
    "    categories=\"Active\",\n",
    "    bound_metabolites={glc__D_c: 1, atp_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_G_CI_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_G_CI_c\",  # CI stands for competitive inhibition\n",
    "    name=\"automatic\",\n",
    "    categories=\"Inhibited\",\n",
    "    bound_metabolites={glc__D_c: 1, _23dpg_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_A_PI_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_A_PI_c\",  # PI stands for competitive inhibition\n",
    "    name=\"automatic\",\n",
    "    categories=\"Inhibited\",\n",
    "    bound_metabolites={adp_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "hex1_G_PI_c = HEX1.make_enzyme_module_form(\n",
    "    \"hex1_G_PI_c\",  # PI stands for competitive inhibition\n",
    "    name=\"automatic\",\n",
    "    categories=\"Inhibited\",\n",
    "    bound_metabolites={g6p_c: 1},\n",
    "    compartment=\"c\")\n",
    "\n",
    "HEX1.enzyme_module_forms"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `bound_metabolites` attribute represents the ligands bound to the site(s) of enzyme."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.237790Z",
     "iopub.status.busy": "2020-10-20T20:35:00.237064Z",
     "iopub.status.idle": "2020-10-20T20:35:00.239713Z",
     "shell.execute_reply": "2020-10-20T20:35:00.240164Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Bound to sites of hex1_c:\n",
      "{}\n",
      "\n",
      "Bound to sites of hex1_A_c:\n",
      "{'atp_c': 1}\n",
      "\n",
      "Bound to sites of hex1_G_c:\n",
      "{'glc__D_c': 1}\n",
      "\n",
      "Bound to sites of hex1_AG_c:\n",
      "{'glc__D_c': 1, 'atp_c': 1}\n",
      "\n",
      "Bound to sites of hex1_G_CI_c:\n",
      "{'glc__D_c': 1, '_23dpg_c': 1}\n",
      "\n",
      "Bound to sites of hex1_A_PI_c:\n",
      "{'adp_c': 1}\n",
      "\n",
      "Bound to sites of hex1_G_PI_c:\n",
      "{'g6p_c': 1}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Print automatically generated names\n",
    "for enzyme_form in HEX1.enzyme_module_forms:\n",
    "    print(\"Bound to sites of {0}:\\n{1}\\n\".format(\n",
    "        enzyme_form.id, {\n",
    "            ligand.id: coeff\n",
    "            for ligand, coeff in enzyme_form.bound_metabolites.items()}))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting the `bound_metabolites` attribute upon creation allow the `formula` and `charge` attributes of the various forms also to be set while ensuring mass and charge balancing is maintained. Note that the enzyme is represented as a moiety, and the ligands bound to the enzyme are represented in the chemical formula."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.250044Z",
     "iopub.status.busy": "2020-10-20T20:35:00.249362Z",
     "iopub.status.idle": "2020-10-20T20:35:00.257271Z",
     "shell.execute_reply": "2020-10-20T20:35:00.257797Z"
    }
   },
   "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>hex1_c</th>\n",
       "      <th>hex1_A_c</th>\n",
       "      <th>hex1_G_c</th>\n",
       "      <th>hex1_AG_c</th>\n",
       "      <th>hex1_G_CI_c</th>\n",
       "      <th>hex1_A_PI_c</th>\n",
       "      <th>hex1_G_PI_c</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>C</th>\n",
       "      <td>0.0</td>\n",
       "      <td>10.0</td>\n",
       "      <td>6.0</td>\n",
       "      <td>16.0</td>\n",
       "      <td>9.0</td>\n",
       "      <td>10.0</td>\n",
       "      <td>6.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>H</th>\n",
       "      <td>0.0</td>\n",
       "      <td>12.0</td>\n",
       "      <td>12.0</td>\n",
       "      <td>24.0</td>\n",
       "      <td>15.0</td>\n",
       "      <td>12.0</td>\n",
       "      <td>11.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O</th>\n",
       "      <td>0.0</td>\n",
       "      <td>13.0</td>\n",
       "      <td>6.0</td>\n",
       "      <td>19.0</td>\n",
       "      <td>16.0</td>\n",
       "      <td>10.0</td>\n",
       "      <td>9.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>P</th>\n",
       "      <td>0.0</td>\n",
       "      <td>3.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>3.0</td>\n",
       "      <td>2.0</td>\n",
       "      <td>2.0</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>N</th>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>S</th>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>q</th>\n",
       "      <td>0.0</td>\n",
       "      <td>-4.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>-4.0</td>\n",
       "      <td>-5.0</td>\n",
       "      <td>-3.0</td>\n",
       "      <td>-2.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>[HEX]</th>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "       hex1_c  hex1_A_c  hex1_G_c  hex1_AG_c  hex1_G_CI_c  hex1_A_PI_c  \\\n",
       "C         0.0      10.0       6.0       16.0          9.0         10.0   \n",
       "H         0.0      12.0      12.0       24.0         15.0         12.0   \n",
       "O         0.0      13.0       6.0       19.0         16.0         10.0   \n",
       "P         0.0       3.0       0.0        3.0          2.0          2.0   \n",
       "N         0.0       5.0       0.0        5.0          0.0          5.0   \n",
       "S         0.0       0.0       0.0        0.0          0.0          0.0   \n",
       "q         0.0      -4.0       0.0       -4.0         -5.0         -3.0   \n",
       "[HEX]     1.0       1.0       1.0        1.0          1.0          1.0   \n",
       "\n",
       "       hex1_G_PI_c  \n",
       "C              6.0  \n",
       "H             11.0  \n",
       "O              9.0  \n",
       "P              1.0  \n",
       "N              0.0  \n",
       "S              0.0  \n",
       "q             -2.0  \n",
       "[HEX]          1.0  "
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get the elemental matrix for the enzyme\n",
    "df = HEX1.get_elemental_matrix(array_type=\"DataFrame\")\n",
    "# Use iloc to only look at EnzymeModuleForms\n",
    "df.iloc[:, 6:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting the `name` argument as \"automatic\" in the `EnzymeModule.make_enzyme_module_form()` method causes a name for the `EnzymeModuleForm` to be generated based on the metabolites in the `bound_metabolites` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.261905Z",
     "iopub.status.busy": "2020-10-20T20:35:00.261201Z",
     "iopub.status.idle": "2020-10-20T20:35:00.263978Z",
     "shell.execute_reply": "2020-10-20T20:35:00.264506Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "HEX1\n",
      "HEX1-atp complex\n",
      "HEX1-glc__D complex\n",
      "HEX1-glc__D-atp complex\n",
      "HEX1-glc__D-_23dpg complex\n",
      "HEX1-adp complex\n",
      "HEX1-g6p complex\n"
     ]
    }
   ],
   "source": [
    "# Print automatically generated names\n",
    "for enzyme_form in HEX1.enzyme_module_forms:\n",
    "    print(enzyme_form.name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `categories` argument allows for `EnzymeModuleForm` objects to be placed into `cobra.Group` objects representing those categories. As with the ligands, the categorized enzyme module forms are returned in a `DictList` of `Group` objects by the `enzyme_module_forms_categorized` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.268980Z",
     "iopub.status.busy": "2020-10-20T20:35:00.268343Z",
     "iopub.status.idle": "2020-10-20T20:35:00.270845Z",
     "shell.execute_reply": "2020-10-20T20:35:00.271290Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Active: ['hex1_AG_c', 'hex1_A_c', 'hex1_G_c', 'hex1_c']\n",
      "Inhibited: ['hex1_A_PI_c', 'hex1_G_CI_c', 'hex1_G_PI_c']\n"
     ]
    }
   ],
   "source": [
    "for group in HEX1.enzyme_module_forms_categorized:\n",
    "    print(\"{0}: {1}\".format(\n",
    "        group.id, str(sorted([m.id for m in group.members]))))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, the `enzyme_module_forms_categorized` attribute can be set using a `dict`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.276199Z",
     "iopub.status.busy": "2020-10-20T20:35:00.275531Z",
     "iopub.status.idle": "2020-10-20T20:35:00.278304Z",
     "shell.execute_reply": "2020-10-20T20:35:00.278752Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Active: ['hex1_AG_c', 'hex1_A_c', 'hex1_G_c', 'hex1_c']\n",
      "Inhibited: ['hex1_A_PI_c', 'hex1_G_CI_c', 'hex1_G_PI_c']\n",
      "competitively_inhibited: ['hex1_G_CI_c']\n"
     ]
    }
   ],
   "source": [
    "HEX1.enzyme_module_forms_categorized =  {\n",
    "    \"competitively_inhibited\": hex1_G_CI_c}\n",
    "\n",
    "for group in HEX1.enzyme_module_forms_categorized:\n",
    "    print(\"{0}: {1}\".format(\n",
    "        group.id, str(sorted([m.id for m in group.members]))))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Defining enzyme module reactions\n",
    "\n",
    "The next step is to define all of the reaction steps that represent the catalytic mechanism and regulation of the enzyme module. These reactions are represented as `EnzymeModuleReaction` objects. \n",
    "\n",
    "The `EnzymeModuleReaction` object inherits from the `MassReaction` and is treated like any other reaction in the model. Like the `make_enzyme_module_form()` method, the `make_enzyme_module_reaction()` method allows for the creation of an `EnzymeModuleReaction` object while assigning categories for the `EnzymeModuleReaction` in the process.\n",
    "\n",
    "Species that exist in the model can also be added to the reaction by providing a dictionary of metabolites and their stoichiometric coefficients to the `metabolites_to_add` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.296397Z",
     "iopub.status.busy": "2020-10-20T20:35:00.295580Z",
     "iopub.status.idle": "2020-10-20T20:35:00.298291Z",
     "shell.execute_reply": "2020-10-20T20:35:00.298699Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "HEX1_1: adp_c + hex1_c <=> hex1_A_PI_c\n",
      "HEX1_2: g6p_c + hex1_c <=> hex1_G_PI_c\n",
      "HEX1_3: glc__D_c + hex1_c <=> hex1_G_c\n",
      "HEX1_4: atp_c + hex1_c <=> hex1_A_c\n",
      "HEX1_5: _23dpg_c + hex1_G_c <=> hex1_G_CI_c\n",
      "HEX1_6: atp_c + hex1_G_c <=> hex1_AG_c\n",
      "HEX1_7: glc__D_c + hex1_A_c <=> hex1_AG_c\n",
      "HEX1_8: hex1_AG_c <=> adp_c + g6p_c + h_c + hex1_c\n"
     ]
    }
   ],
   "source": [
    "HEX1_1 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_1\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"product_inhibition\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_c\": -1,\n",
    "        \"adp_c\": -1,\n",
    "        \"hex1_A_PI_c\": 1})\n",
    "\n",
    "HEX1_2 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_2\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"product_inhibition\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_c\": -1,\n",
    "        \"g6p_c\": -1,\n",
    "        \"hex1_G_PI_c\": 1})\n",
    "\n",
    "HEX1_3 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_3\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"glc__D_c_binding\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_c\": -1,\n",
    "        \"glc__D_c\": -1,\n",
    "        \"hex1_G_c\": 1})\n",
    "\n",
    "HEX1_4 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_4\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"atp_c_binding\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_c\": -1,\n",
    "        \"atp_c\": -1,\n",
    "        \"hex1_A_c\": 1})\n",
    "\n",
    "HEX1_5 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_5\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"competitive_inhibition\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_G_c\": -1,\n",
    "        \"_23dpg_c\": -1,\n",
    "        \"hex1_G_CI_c\": 1})\n",
    "\n",
    "HEX1_6 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_6\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"atp_c_binding\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_G_c\": -1,\n",
    "        \"atp_c\": -1,\n",
    "        \"hex1_AG_c\": 1})\n",
    "\n",
    "HEX1_7 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_7\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"glc__D_c_binding\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_A_c\": -1,\n",
    "        \"glc__D_c\": -1,\n",
    "        \"hex1_AG_c\": 1})\n",
    "\n",
    "HEX1_8 = HEX1.make_enzyme_module_reaction(\n",
    "    \"HEX1_8\",\n",
    "    name=\"Automatic\",\n",
    "    subsystem=\"Glycolysis\",\n",
    "    reversible=True,\n",
    "    categories=\"catalyzation\",\n",
    "    metabolites_to_add={\n",
    "        \"hex1_AG_c\": -1,\n",
    "        \"hex1_c\": 1,\n",
    "        \"adp_c\": 1,\n",
    "        \"g6p_c\": 1,\n",
    "        \"h_c\": 1})\n",
    "\n",
    "for reaction in HEX1.enzyme_module_reactions:\n",
    "    print(reaction)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `categories` argument allows for `EnzymeModuleReactions` objects to be placed into `cobra.Group` objects representing those categories. As with the ligands and enzyme forms, a `DictList` of the relevant groups are returned with the `enzyme_module_reactions_categorized` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.303526Z",
     "iopub.status.busy": "2020-10-20T20:35:00.302825Z",
     "iopub.status.idle": "2020-10-20T20:35:00.306213Z",
     "shell.execute_reply": "2020-10-20T20:35:00.306667Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<Group product_inhibition at 0x7ff42b87ae10>,\n",
       " <Group glc__D_c_binding at 0x7ff42b87c650>,\n",
       " <Group atp_c_binding at 0x7ff42b87ca50>,\n",
       " <Group competitive_inhibition at 0x7ff42b87cc90>,\n",
       " <Group catalyzation at 0x7ff42b85ef50>]"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "HEX1.enzyme_module_reactions_categorized"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Unifying rate parameters\n",
    "\n",
    "For this `EnzymeModule`, the reactions representing glucose binding to the enzyme and ATP binding to the enzyme have the same forward rate and equilibrium constants. Instead of defining the parameter values for each individual reaction, the `unify_rate_parameters()` method can be used to create custom rate laws for the given reactions that all depend on the same rate parameters.\n",
    "\n",
    "The `unify_rate_parameters()` method takes a list of reactions and an identifier to use for the unified parameter. The `enzyme_prefix` flag can be set to `True` to prefix the new parameter identifier with the identifier of the `EnzymeModule`, ensuring that any existing custom parameters are not overwritten."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.365298Z",
     "iopub.status.busy": "2020-10-20T20:35:00.346693Z",
     "iopub.status.idle": "2020-10-20T20:35:00.367853Z",
     "shell.execute_reply": "2020-10-20T20:35:00.368333Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "glc__D_c_binding\n",
      "----------------\n",
      "HEX1_3: kf_HEX1_G*(glc__D_c(t)*hex1_c(t) - hex1_G_c(t)/Keq_HEX1_G)\n",
      "HEX1_7: kf_HEX1_G*(glc__D_c(t)*hex1_A_c(t) - hex1_AG_c(t)/Keq_HEX1_G)\n",
      "\n",
      "atp_c_binding\n",
      "-------------\n",
      "HEX1_4: kf_HEX1_A*(atp_c(t)*hex1_c(t) - hex1_A_c(t)/Keq_HEX1_A)\n",
      "HEX1_6: kf_HEX1_A*(atp_c(t)*hex1_G_c(t) - hex1_AG_c(t)/Keq_HEX1_A)\n"
     ]
    }
   ],
   "source": [
    "for ligand, pid in zip([glc__D_c, atp_c],[\"G\", \"A\"]):\n",
    "    # Get the group of reactions corresponding to the ligand\n",
    "    category = \"_\".join((ligand.id, \"binding\"))\n",
    "    group = HEX1.enzyme_module_reactions_categorized.get_by_id(category)\n",
    "    \n",
    "    # Unify the parameters\n",
    "    HEX1.unify_rate_parameters(\n",
    "        group.members, new_parameter_id=pid, enzyme_prefix=True)\n",
    "\n",
    "    # Print the new reaction rates\n",
    "    print(\"\\n\" + category + \"\\n\" + \"-\" * len(category))\n",
    "    for reaction in sorted(group.members, key=attrgetter(\"id\")):\n",
    "        print(reaction.id + \": \" + str(reaction.rate))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Determining Enzyme Form Concentrations and Rate Constants\n",
    "\n",
    "The next step is to solve for the steady state concentrations for the various forms of the enzyme symbolically using **SymPy**. Because the numerical values for the dissociation constants have been defined, these equations are solved in terms of the rate constants. The rate constants can be approximated using the total enzyme concentration as a constraint and substituted back into the equations to calculate the numerical values of the steady state concentrations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.372578Z",
     "iopub.status.busy": "2020-10-20T20:35:00.371903Z",
     "iopub.status.idle": "2020-10-20T20:35:00.374201Z",
     "shell.execute_reply": "2020-10-20T20:35:00.374661Z"
    }
   },
   "outputs": [],
   "source": [
    "from sympy import Eq, Symbol, lambdify, simplify, solveset\n",
    "\n",
    "from mass import strip_time\n",
    "from mass.util.matrix import matrix_rank"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Solving steady state concentrations symbolically\n",
    "\n",
    "To get the symbolic solutions for the individual enzyme forms, the ODEs are first collected in a `dict`. Keys are the enzyme forms, and values are their ODEs with the time dependency stripped via the `strip_time` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.461608Z",
     "iopub.status.busy": "2020-10-20T20:35:00.418071Z",
     "iopub.status.idle": "2020-10-20T20:35:00.559505Z",
     "shell.execute_reply": "2020-10-20T20:35:00.559028Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Rank Deficiency: 1\n"
     ]
    }
   ],
   "source": [
    "ode_dict = {\n",
    "    enzyme_form.id: Eq(strip_time(enzyme_form.ode), 0)\n",
    "    for enzyme_form in HEX1.enzyme_module_forms}\n",
    "# Matrix rank of enzyme stoichiometric matrix without substrates\n",
    "rank = matrix_rank(HEX1.S[6:])\n",
    "print(\"Rank Deficiency: {0}\".format(len(ode_dict) - rank))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the stoichiometric matrix (without ligands) has a rank deficiency of one, there is a dependent variable in the system unless another equation is added. Therefore, the completely free enzyme form is treated as the dependent variable, and all of the enzyme forms are solved in terms of the free enzyme form."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:00.566245Z",
     "iopub.status.busy": "2020-10-20T20:35:00.565591Z",
     "iopub.status.idle": "2020-10-20T20:35:04.648456Z",
     "shell.execute_reply": "2020-10-20T20:35:04.648907Z"
    }
   },
   "outputs": [],
   "source": [
    "enzyme_solutions = {}\n",
    "for enzyme_form in HEX1.enzyme_module_forms:\n",
    "    # Skip dependent variable\n",
    "    if enzyme_form.id == \"hex1_c\":\n",
    "        continue\n",
    "    # Get the ODE for the enzyme form from the ODE dict\n",
    "    equation = ode_dict[enzyme_form.id]\n",
    "    # Solve the equation for the enzyme form, substituting \n",
    "    # previously found enzyme form solutions into the equation\n",
    "    solution = solveset(equation.subs(enzyme_solutions),\n",
    "                        enzyme_form.id)\n",
    "    # Store the solution\n",
    "    enzyme_solutions[enzyme_form.id] = list(solution)[0]\n",
    "    # Substitute the new solution into existing solutions\n",
    "    enzyme_solutions.update({\n",
    "        enzyme_form: sol.subs(enzyme_solutions) \n",
    "        for enzyme_form, sol in enzyme_solutions.items()})\n",
    "    \n",
    "args = set()\n",
    "for solution in enzyme_solutions.values():\n",
    "    args.update(solution.atoms(Symbol))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Defining the Rate Equation\n",
    "\n",
    "To make up for the rank deficiency, an additional equation is needed. Typically, the rate of the enzyme is the summation of the rates for the catalyzation reaction step(s) of the enzyme. The `make_enzyme_rate_equation()` method can be used to create the rate equation from a list of reactions. If `use_rates=True`, the rate expressions of the reactions are added together. If `update_enzyme=True`, the rate equation is set as a symbolic expression for the `enzyme_rate_equation` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:04.705603Z",
     "iopub.status.busy": "2020-10-20T20:35:04.694988Z",
     "iopub.status.idle": "2020-10-20T20:35:04.708752Z",
     "shell.execute_reply": "2020-10-20T20:35:04.708228Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "kf_HEX1_8*(Keq_HEX1_8*hex1_AG_c(t) - adp_c(t)*g6p_c(t)*hex1_c(t))/Keq_HEX1_8\n"
     ]
    }
   ],
   "source": [
    "# Get the catalyzation reactions\n",
    "catalyzation_group = HEX1.enzyme_module_reactions_categorized.get_by_id(\n",
    "    \"catalyzation\")\n",
    "\n",
    "HEX1.make_enzyme_rate_equation(catalyzation_group.members,\n",
    "                               use_rates=True,\n",
    "                               update_enzyme=True)\n",
    "\n",
    "print(HEX1.enzyme_rate_equation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the rate equation defined, the `enzyme_rate_error()` method is used to get the equation as the difference between the flux value and the rate equation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:04.719498Z",
     "iopub.status.busy": "2020-10-20T20:35:04.718841Z",
     "iopub.status.idle": "2020-10-20T20:35:04.721338Z",
     "shell.execute_reply": "2020-10-20T20:35:04.721782Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "v_HEX1 - kf_HEX1_8*(Keq_HEX1_8*hex1_AG_c - adp_c*g6p_c*hex1_c)/Keq_HEX1_8\n"
     ]
    }
   ],
   "source": [
    "enzyme_rate_equation = strip_time(HEX1.enzyme_rate_error(use_values=False))\n",
    "print(enzyme_rate_equation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The solutions for the enzyme forms are substituted into the rate equation, and the equation is solved for the free enzyme form. The solutions are subsequently updated, resulting in symbolic equations that do not depend on any enzyme form."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:04.810789Z",
     "iopub.status.busy": "2020-10-20T20:35:04.767341Z",
     "iopub.status.idle": "2020-10-20T20:35:24.794597Z",
     "shell.execute_reply": "2020-10-20T20:35:24.795038Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{g6p_c, kf_HEX1_8, kf_HEX1_A, v_HEX1, Keq_HEX1_A, atp_c, glc__D_c, _23dpg_c, kf_HEX1_G, Keq_HEX1_5, Keq_HEX1_8, adp_c, Keq_HEX1_2, Keq_HEX1_1, Keq_HEX1_G}\n"
     ]
    }
   ],
   "source": [
    "# Solve for last unknown concentration symbolically\n",
    "solution = solveset(enzyme_rate_equation.subs(enzyme_solutions),\n",
    "                    \"hex1_c\")\n",
    "\n",
    "# Update solution dictionary with the new solution\n",
    "enzyme_solutions[\"hex1_c\"] = list(solution)[0]\n",
    "\n",
    "# Update solutions with free variable solutions\n",
    "enzyme_solutions = {\n",
    "    enzyme_form: simplify(solution.subs(enzyme_solutions))\n",
    "    for enzyme_form, solution in enzyme_solutions.items()}\n",
    "\n",
    "args = set()\n",
    "for solution in enzyme_solutions.values():\n",
    "    args.update(solution.atoms(Symbol))\n",
    "print(args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Numerical values for known quantities are substituted into the equations. For this `EnzymeModule` of Hexokinase, the following dissociation constants are used:\n",
    "\n",
    "$$\\begin{align}\n",
    "K_{d,\\ \\text{GLC-D}} &= 0.038\\ \\text{mM} \\\\\n",
    "K_{d,\\ \\text{ATP}} &= 2.06\\ \\text{mM} \\\\\n",
    "K_{i,\\ \\text{23DPG}} &= 5.5\\ \\text{mM} \\\\\n",
    "K_{i,\\ \\text{ADP}} &= 1\\ \\text{mM} \\\\\n",
    "K_{i,\\ \\text{G6P}} &= 66.67\\ \\text{mM} \\\\\n",
    "\\end{align}$$\n",
    "\n",
    "A value of $K_{\\text{HEX1}}= 313.12$ is used for the catalyzation step. Note that the inverse of the dissociation constant is used for reactions that form complexes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:24.800084Z",
     "iopub.status.busy": "2020-10-20T20:35:24.799340Z",
     "iopub.status.idle": "2020-10-20T20:35:24.801263Z",
     "shell.execute_reply": "2020-10-20T20:35:24.801758Z"
    }
   },
   "outputs": [],
   "source": [
    "numerical_values = {\n",
    "    \"Keq_HEX1_1\": 1,\n",
    "    \"Keq_HEX1_2\": 1 / 66.67,\n",
    "    \"Keq_HEX1_G\": 1 / 0.038,  \n",
    "    \"Keq_HEX1_A\": 1 / 2.06,\n",
    "    \"Keq_HEX1_5\": 1 / 5.5,\n",
    "    \"Keq_HEX1_8\": 313.12}\n",
    "# Update the model with the parameters\n",
    "HEX1.update_parameters(numerical_values)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ligand concentrations and the rate for the enzyme are extracted from the merged glycolysis and hemoglobin model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:24.806734Z",
     "iopub.status.busy": "2020-10-20T20:35:24.806085Z",
     "iopub.status.idle": "2020-10-20T20:35:24.808331Z",
     "shell.execute_reply": "2020-10-20T20:35:24.808856Z"
    }
   },
   "outputs": [],
   "source": [
    "# Get steady state flux for EnzymeModule\n",
    "HEX1.enzyme_rate = glyc_hb.reactions.get_by_id(\"HEX1\").steady_state_flux\n",
    "numerical_values[HEX1.enzyme_flux_symbol_str] = HEX1.enzyme_rate\n",
    "\n",
    "# Get the ligand concentrations\n",
    "for met in HEX1.enzyme_module_ligands:\n",
    "    concentration = glyc_hb.metabolites.get_by_id(met.id).initial_condition\n",
    "    # Set the ligand initial condition and add to numercal values dictionary\n",
    "    met.initial_condition = concentration\n",
    "    numerical_values[met.id] = concentration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The numerical values are substituted into the symbolic equations, resulting in the steady state concentrations that depend only on the rate constants."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:24.898362Z",
     "iopub.status.busy": "2020-10-20T20:35:24.854647Z",
     "iopub.status.idle": "2020-10-20T20:35:25.805392Z",
     "shell.execute_reply": "2020-10-20T20:35:25.805855Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{kf_HEX1_A, kf_HEX1_G, kf_HEX1_8}\n"
     ]
    }
   ],
   "source": [
    "enzyme_solutions = {\n",
    "    enzyme_form: simplify(sol.subs(numerical_values))\n",
    "    for enzyme_form, sol in enzyme_solutions.items()}\n",
    "\n",
    "args = set()\n",
    "for solution in enzyme_solutions.values():\n",
    "    args.update(solution.atoms(Symbol))\n",
    "print(args)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Approximating Rate Constants\n",
    "\n",
    "To determine the set of rate constants for the enzyme module, the absolute error between the total hexokinase concentration value (found in literature) and the computed hexokinase concentration is minimized. For this example, the `minimize()` function of the **SciPy** package is utilized to find a feasible set of rate constants. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:25.810118Z",
     "iopub.status.busy": "2020-10-20T20:35:25.809365Z",
     "iopub.status.idle": "2020-10-20T20:35:25.811931Z",
     "shell.execute_reply": "2020-10-20T20:35:25.812500Z"
    }
   },
   "outputs": [],
   "source": [
    "from scipy.optimize import minimize"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The objective function for the minimization is first made symbolically. The `enzyme_total_symbol_str` property can be used to represent the total enzyme concentration, while the `enzyme_concentration_total_equation` property creates a symbolic expression for the sum of all enzyme forms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:25.839961Z",
     "iopub.status.busy": "2020-10-20T20:35:25.839082Z",
     "iopub.status.idle": "2020-10-20T20:35:25.841954Z",
     "shell.execute_reply": "2020-10-20T20:35:25.842396Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Abs(-HEX1_Total + hex1_AG_c + hex1_A_PI_c + hex1_A_c + hex1_G_CI_c + hex1_G_PI_c + hex1_G_c + hex1_c)\n"
     ]
    }
   ],
   "source": [
    "enzyme_total_error = abs(\n",
    "    Symbol(HEX1.enzyme_total_symbol_str)\n",
    "    - strip_time(HEX1.enzyme_concentration_total_equation))\n",
    "print(enzyme_total_error)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `enzyme_concentration_total` attribute stores the total amount of enzyme in the model and substituted into the expression. The total HEX1 concentration is $24 * 10^{-6} \\text{mM}$."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:25.858017Z",
     "iopub.status.busy": "2020-10-20T20:35:25.857314Z",
     "iopub.status.idle": "2020-10-20T20:35:25.860011Z",
     "shell.execute_reply": "2020-10-20T20:35:25.860458Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Abs(hex1_AG_c + hex1_A_PI_c + hex1_A_c + hex1_G_CI_c + hex1_G_PI_c + hex1_G_c + hex1_c - 2.4e-5)\n"
     ]
    }
   ],
   "source": [
    "HEX1.enzyme_concentration_total = 24e-6\n",
    "enzyme_total_error = enzyme_total_error.subs({\n",
    "    HEX1.enzyme_total_symbol_str: HEX1.enzyme_concentration_total})\n",
    "print(enzyme_total_error)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, the symbolic equations for the enzyme forms are substituted into the enzyme total error equation, resulting in an expression that represents the objective function with the only unknown variables being rate constants. The `lambdify()` function of the **SymPy** package converts the symbolic objective into a lambda function that can be used with the `minimize()` function of **SciPy**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:25.948351Z",
     "iopub.status.busy": "2020-10-20T20:35:25.906315Z",
     "iopub.status.idle": "2020-10-20T20:35:26.755890Z",
     "shell.execute_reply": "2020-10-20T20:35:26.756322Z"
    }
   },
   "outputs": [],
   "source": [
    "enzyme_total_error = simplify(enzyme_total_error.subs(enzyme_solutions))\n",
    "\n",
    "# Sort the arguments to ensure input format remains consistent\n",
    "args = sorted(list(map(str, args)))\n",
    "# Use lambdify to make objective function as a lambda function\n",
    "obj_fun = lambda x: lambdify(args, enzyme_total_error)(*x)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `minimize()` function is now used to approximate the rate constants. The optimization problems for enzyme rate constants are typically nonlinear, and require nonlinear optimization routines to find feasible solutions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:26.797825Z",
     "iopub.status.busy": "2020-10-20T20:35:26.797131Z",
     "iopub.status.idle": "2020-10-20T20:35:26.878904Z",
     "shell.execute_reply": "2020-10-20T20:35:26.879434Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'kf_HEX1_8': 100000000.0025878, 'kf_HEX1_A': 9376585.030755484, 'kf_HEX1_G': 52006.59981223971}\n"
     ]
    }
   ],
   "source": [
    "# Minimize the objective function, initial guess based on publication values\n",
    "initial_guess = [1e8, 9376585, 52001]\n",
    "variable_bounds = ((0, 1e9), (0, 1e9), (0, 1e9))\n",
    "solution = minimize(obj_fun, x0=initial_guess,\n",
    "                    method=\"trust-constr\",\n",
    "                    bounds=variable_bounds)\n",
    "# Map solution array to variables\n",
    "rate_constants = dict(zip(args, solution.x))\n",
    "print(rate_constants)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the rate constants associated with the inhibition of the enzyme forms are not necessary for computing the concentrations, a rapid binding assumption is made for the inhibition reactions. Therefore, a large number is set for the rate constants. The parameters are set using the `update_parameters()` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:26.884660Z",
     "iopub.status.busy": "2020-10-20T20:35:26.883949Z",
     "iopub.status.idle": "2020-10-20T20:35:26.886084Z",
     "shell.execute_reply": "2020-10-20T20:35:26.886576Z"
    }
   },
   "outputs": [],
   "source": [
    "rate_constants[\"kf_HEX1_1\"] = 1e6\n",
    "rate_constants[\"kf_HEX1_2\"] = 1e6\n",
    "rate_constants[\"kf_HEX1_5\"] = 1e6\n",
    "HEX1.update_parameters(rate_constants)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calculating numerical values for concentrations\n",
    "\n",
    "Once the rate constants have been estimated, they are substituted back into the symbolic concentration equations in order to obtain their numerical values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.052403Z",
     "iopub.status.busy": "2020-10-20T20:35:26.926145Z",
     "iopub.status.idle": "2020-10-20T20:35:27.078951Z",
     "shell.execute_reply": "2020-10-20T20:35:27.079412Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "hex1_A_c: 9.401421e-06\n",
      "hex1_G_c: 5.718872e-08\n",
      "hex1_AG_c: 1.174630e-08\n",
      "hex1_G_CI_c: 3.223364e-08\n",
      "hex1_A_PI_c: 3.519706e-06\n",
      "hex1_G_PI_c: 8.847367e-09\n",
      "hex1_c: 1.213692e-05\n"
     ]
    }
   ],
   "source": [
    "for enzyme_form, solution in enzyme_solutions.items():\n",
    "    # Get the enzyme form object, determine the steady state concentration\n",
    "    enzyme_form = HEX1.enzyme_module_forms.get_by_id(enzyme_form)\n",
    "    enzyme_form.initial_condition = float(solution.subs(rate_constants))\n",
    "    print(\"{0}: {1:e}\".format(enzyme_form.id,\n",
    "                              enzyme_form.initial_condition))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Error values\n",
    "\n",
    "As a quality assurance check, the `enzyme_concentration_total_error()` method can be used to get the error between the `enzyme_concentration_total` attribute and the sum of the enzyme form concentrations. A positive value indicates the `enzyme_concentration_total` attribute is greater than the sum of the individual enzyme form concentrations that were computed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.104527Z",
     "iopub.status.busy": "2020-10-20T20:35:27.103790Z",
     "iopub.status.idle": "2020-10-20T20:35:27.106635Z",
     "shell.execute_reply": "2020-10-20T20:35:27.107176Z"
    },
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Total Enzyme Concentration Error: -1.1680622689093244e-06\n"
     ]
    }
   ],
   "source": [
    "print(\"Total Enzyme Concentration Error: {0}\".format(\n",
    "    HEX1.enzyme_concentration_total_error(use_values=True)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, the error between the `enzyme_rate` attribute and the computed value from the `enzyme_rate_equation` can be also checked using the `enzyme_rate_error()` method, in which a positive value indicates that the `enzyme_rate` attribute is greater than the value computed when using the rate equation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.124192Z",
     "iopub.status.busy": "2020-10-20T20:35:27.123219Z",
     "iopub.status.idle": "2020-10-20T20:35:27.126162Z",
     "shell.execute_reply": "2020-10-20T20:35:27.126607Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Enzyme Rate Error: 4.440892098500626e-16\n"
     ]
    }
   ],
   "source": [
    "print(\"Enzyme Rate Error: {0}\".format(\n",
    "    HEX1.enzyme_rate_error(use_values=True)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding EnzymeModules to Models\n",
    "\n",
    "With the `EnzymeModule` built, it can be integrated into a larger network and simulated. To add an `EnzymeModule` to an existing `MassModel`, the `merge()` method is used. After merging, the `remove_reactions()` method is used to remove the reaction replaced with the enzyme module. The `EnzymeModule` should always be merged into the `MassModel` as demonstrated below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.133472Z",
     "iopub.status.busy": "2020-10-20T20:35:27.132773Z",
     "iopub.status.idle": "2020-10-20T20:35:27.188627Z",
     "shell.execute_reply": "2020-10-20T20:35:27.188148Z"
    }
   },
   "outputs": [],
   "source": [
    "glyc_hb_HEX1 = glyc_hb.merge(HEX1, inplace=False)\n",
    "glyc_hb_HEX1.remove_reactions([\n",
    "    glyc_hb_HEX1.reactions.get_by_id(\"HEX1\")])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All objects, numerical values, and certain attributes of the `EnzymeModule` are transferred into the `MassModel` upon merging. This includes all enzyme forms, reactions steps, initial conditions, rate parameters, and category groups."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.194154Z",
     "iopub.status.busy": "2020-10-20T20:35:27.193401Z",
     "iopub.status.idle": "2020-10-20T20:35:27.196385Z",
     "shell.execute_reply": "2020-10-20T20:35:27.196833Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "            <table>\n",
       "                <tr>\n",
       "                    <td><strong>Name</strong></td><td>Glycolysis_Hemoglobin_HEX1</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Memory address</strong></td><td>0x07ff42b8e6d90</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Stoichiometric Matrix</strong></td>\n",
       "                    <td>35x37</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Matrix Rank</strong></td>\n",
       "                    <td>32</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of metabolites</strong></td>\n",
       "                    <td>35</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Initial conditions defined</strong></td>\n",
       "                    <td>35/35</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of reactions</strong></td>\n",
       "                    <td>37</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of genes</strong></td>\n",
       "                    <td>0</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of enzyme modules</strong></td>\n",
       "                    <td>1</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of groups</strong></td>\n",
       "                    <td>12</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Objective expression</strong></td>\n",
       "                    <td>0</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Compartments</strong></td>\n",
       "                    <td>Cytosol</td>\n",
       "                </tr>\n",
       "            </table>\n",
       "        "
      ],
      "text/plain": [
       "<MassModel Glycolysis_Hemoglobin_HEX1 at 0x7ff42b8e6d90>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "glyc_hb_HEX1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The EnzymeModuleDict object\n",
    "\n",
    "During the merge process, an `EnzymeModuleDict` is created from the `EnzymeModule` and added to the `MassModel.enzyme_modules` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.202084Z",
     "iopub.status.busy": "2020-10-20T20:35:27.201299Z",
     "iopub.status.idle": "2020-10-20T20:35:27.204922Z",
     "shell.execute_reply": "2020-10-20T20:35:27.205370Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[<EnzymeModuleDict HEX1 at 0x7ff42bab8950>]\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "\n",
       "            <table>\n",
       "                <tr>\n",
       "                    <td><strong>Name</strong></td><td>HEX1</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Memory address</strong></td><td>0x07ff42bab8950</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Stoichiometric Matrix</strong></td>\n",
       "                    <td>13x8</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Matrix Rank</strong></td>\n",
       "                    <td>7</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Subsystem</strong></td>\n",
       "                    <td>Glycolysis</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of Ligands</strong></td>\n",
       "                    <td>6</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of EnzymeForms</strong></td>\n",
       "                    <td>7</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Number of EnzymeModuleReactions</strong></td>\n",
       "                    <td>8</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Enzyme Concentration Total</strong></td>\n",
       "                    <td>2.4e-05</td>\n",
       "                </tr><tr>\n",
       "                    <td><strong>Enzyme Net Flux</strong></td>\n",
       "                    <td>1.12</td>\n",
       "                </tr>\n",
       "            </table>\n",
       "        "
      ],
      "text/plain": [
       "<EnzymeModuleDict HEX1 at 0x7ff42bab8950>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "print(glyc_hb_HEX1.enzyme_modules)\n",
    "HEX1_dict = glyc_hb_HEX1.enzyme_modules.get_by_id(\"HEX1\")\n",
    "HEX1_dict"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EnzymeModuleDict` inherits from an `OrderedDict`, thereby inheriting ordered dictionary methods such as `keys()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.209604Z",
     "iopub.status.busy": "2020-10-20T20:35:27.208881Z",
     "iopub.status.idle": "2020-10-20T20:35:27.211356Z",
     "shell.execute_reply": "2020-10-20T20:35:27.211802Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "id\n",
      "name\n",
      "subsystem\n",
      "enzyme_module_ligands\n",
      "enzyme_module_forms\n",
      "enzyme_module_reactions\n",
      "enzyme_module_ligands_categorized\n",
      "enzyme_module_forms_categorized\n",
      "enzyme_module_reactions_categorized\n",
      "enzyme_concentration_total\n",
      "enzyme_rate\n",
      "enzyme_concentration_total_equation\n",
      "enzyme_rate_equation\n",
      "S\n",
      "model\n"
     ]
    }
   ],
   "source": [
    "print(\"\\n\".join(HEX1_dict.keys()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EnzymeModuleDict` stores several of the enzyme-specific attributes so that they are still accessible after integrating the enzyme module into a larger network. The keys of the `EnzymeModuleDict`  also can be treated as attribute accessors:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.216895Z",
     "iopub.status.busy": "2020-10-20T20:35:27.216200Z",
     "iopub.status.idle": "2020-10-20T20:35:27.218644Z",
     "shell.execute_reply": "2020-10-20T20:35:27.219087Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Enzyme Rate:\n",
      "1.12 = kf_HEX1_8*(Keq_HEX1_8*hex1_AG_c(t) - adp_c(t)*g6p_c(t)*hex1_c(t))/Keq_HEX1_8\n"
     ]
    }
   ],
   "source": [
    "print(\"Enzyme Rate:\\n{0} = {1}\".format(\n",
    "    HEX1_dict[\"enzyme_rate\"],       # Returned using dict key\n",
    "    HEX1_dict.enzyme_rate_equation  # Returned using attribute accessor\n",
    "))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Steady State Validation\n",
    "The last step is to ensure that a steady state is reached with the completed enzyme module within a larger network context."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.223492Z",
     "iopub.status.busy": "2020-10-20T20:35:27.222808Z",
     "iopub.status.idle": "2020-10-20T20:35:27.224934Z",
     "shell.execute_reply": "2020-10-20T20:35:27.225384Z"
    }
   },
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from mass import Simulation\n",
    "from mass.visualization import plot_time_profile"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the model is simulated, and the enzyme's ability to reach steady state is graphically verified: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2020-10-20T20:35:27.312662Z",
     "iopub.status.busy": "2020-10-20T20:35:27.269619Z",
     "iopub.status.idle": "2020-10-20T20:35:29.051337Z",
     "shell.execute_reply": "2020-10-20T20:35:29.051792Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Successfully loaded MassModel 'Glycolysis_Hemoglobin_HEX1' into RoadRunner.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<matplotlib.axes._subplots.AxesSubplot at 0x7ff426323c10>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Setup simulation object\n",
    "sim = Simulation(glyc_hb_HEX1, verbose=True)\n",
    "# Simulate from 0 to 1000 with 10001 points in the output\n",
    "conc_sol, flux_sol = sim.simulate(\n",
    "    glyc_hb_HEX1, time=(0, 1e3, 1e4 + 1))\n",
    "\n",
    "fig, ax = plt.subplots(nrows=1, ncols=1, figsize=(6, 4))\n",
    "plot_time_profile(\n",
    "    conc_sol, observable=HEX1_dict.enzyme_module_forms, ax=ax,\n",
    "    legend=\"right outside\", plot_function=\"loglog\",\n",
    "    xlabel=\"Time [hr]\", ylabel=\"Concentration [mM]\",\n",
    "    title=\"TIme profile of Concentrations for Enzyme Forms\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The plot shows that the enzyme can reach a steady state when integrated into a larger network, meaning the enzyme module that represents hexokinase in this system is complete!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional Examples\n",
    "For additional examples of analyzing and visualizing systems with enzyme modules, see the following: \n",
    "\n",
    "* [Visualizing Catalytic Potentials of Glycolytic Regulatory Kinases](../gallery/visualization/catalytic_potential_visualizations.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$^1$ Procedure outlined in <cite data-cite=\"DZK+16\">Du et al., 2016</cite>\n",
    "\n",
    "$^2$ Hexokinase based on <cite data-cite=\"YAHP18\">Yurkovich et al., 2018</cite>, <cite data-cite=\"DZK+16\">Du et al., 2016</cite>, and <cite data-cite=\"MK99\">Mulquiney and Kuchel, 1999.</cite>\n",
    "\n",
    "$^3$ Glycolysis model based on <cite data-cite=\"YAHP18\">Yurkovich et al., 2018</cite> and Chapter 10 of <cite data-cite=\"Pal11\">Systems Biology: Simulation of Dynamic Network States</cite>"
   ]
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}