tutorials/Model creation and edition with minibn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Python API for Boolean and multi-valued network specification\n",
    "\n",
    "The module `colomoto.minibn` offers a simple programmatic way to define and modify Boolean and multi-valued networks.\n",
    "The network can then be converted to bioLQM for analysis.\n",
    "\n",
    "Functions can be specified either as a string, or using standard Python logic operators (`~` for NOT; `&` for AND; `|` for OR).\n",
    "\n",
    "## Boolean networks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from colomoto.minibn import BooleanNetwork"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "f = BooleanNetwork()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An object of type `BooleanNetwork` extends standard Python dictionnaries to specify for each node (key) the corresponding Boolean function.\n",
    "\n",
    "To use a programmatic specifiction of functions, the variables for nodes are declared as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "a, b, c = f.vars(\"a\", \"b\", \"c\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "f[a] = ~b & c\n",
    "f[b] = ~a\n",
    "f[c] = 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Boolean expression can be stored in variables to reuse in more complex expressions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "d = b & c\n",
    "f[b] = d\n",
    "f[c] = ~d"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a <- !b&c\n",
       "b <- b&c\n",
       "c <- !(b&c)\n"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Boolean network can also be specified directly as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = BooleanNetwork({\n",
    "    \"a\": \"!b & c\",\n",
    "    \"b\": \"a\",\n",
    "    \"c\": \"1\"\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Functions for `g` can then be edited as a standard dictionnary, using either the programmatic specification of expression or giving their string representation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "g[\"b\"] = \"b&c\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "b, c = g.vars(\"b\", \"c\")\n",
    "g[c] = ~(b&c)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a <- !b&c\n",
       "b <- b&c\n",
       "c <- !(b&c)\n"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Rewriting expressions\n",
    "\n",
    "The method `rewrite` allows to substitute literals with Boolean expressions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a <- !b&c\n",
       "b <- b&(a|c)\n",
       "c <- !(b&c)\n"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g.rewrite(b, {c: a|c})\n",
    "g"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a <- !b&c\n",
       "b <- b&(a|c)\n",
       "c <- !c\n"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g.rewrite(\"c\", {b:1})\n",
    "g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Conversion to bioLQM\n",
    "\n",
    "An object of type `BooleanNetwork` has a method `to_biolqm` to convert the object to a full bioLQM object and perform further analysis or convert to other tools."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "import biolqm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "lqm = f.to_biolqm()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "from colomoto_jupyter import tabulate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    |   a |   b |   c |\n",
       "|---:|----:|----:|----:|\n",
       "|  0 |   1 |   0 |   1 |"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tabulate(biolqm.fixpoints(lqm))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Multi-Valued networks\n",
    "\n",
    "Specification of multi-valued networks essentially extends `BooleanNetwork` features with ability to refer to levels of nodes and specify an ordering for the evaluation of the discrete expression.\n",
    "\n",
    "Levels are specified programmatically using the syntax `a/i` (represented as a string with `\"a:i\"`) where `a` is a node variable of the network and `i` an integer. This variable is true when the current level of `a` is greater or equal to `i`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from colomoto.minibn import MultiValuedNetwork"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvf = MultiValuedNetwork()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "a, b, c, d = mvf.vars(\"a\", \"b\", \"c\", \"d\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Discrete functions can be specified using dictionnary giving the condition to reach the different levels. With this specification, the function will evaluate to the highest level having a verified condition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvf[a] = {1: b/1, \n",
    "          2: b/1 & c}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A more fine-grained specification allow to define the precise ordering of evaluation (the last win):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvf.append(b/2, a/2 | ~c)\n",
    "mvf.append(b/1, a/2 & c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Multi-valued networks can include pure Boolean node, and are specified as with `BooleanNetwork`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvf[c] = c & ~(a/2) # notice the parentheses to comply with operators priority"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a:1 <- b:1\n",
       "a:2 <- b:1&c\n",
       "b:2 <- a:2|!c\n",
       "b:1 <- a:2&c\n",
       "c <- c&!a:2\n"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mvf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Conditions on levels can also be specified using standard comparison operators:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a:1 <- !b:3\n",
       "a:0 <- !b:2\n",
       "a:3 <- b:2\n",
       "a:4 <- b:3\n",
       "a:2 <- b:2&!b:3\n",
       "c <- !b:2|b:3\n"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mvg = MultiValuedNetwork()\n",
    "a, b, c = mvg.vars(\"a\", \"b\", \"c\")\n",
    "mvg.append(a/1, (b<=2))\n",
    "mvg.append(a/0, (b<2))\n",
    "mvg.append(a/3, (b>=2))\n",
    "mvg.append(a/4, (b>2))\n",
    "mvg.append(a/2, (b==2))\n",
    "mvg[c] = (b!=2)\n",
    "mvg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A multi-valued network can also be instanciated with its textual representation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "mvg = MultiValuedNetwork(\"\"\"\n",
    "a:1 <- b:1\n",
    "a:2 <- b:1 & c\n",
    "b:1 <- a:2\n",
    "b:2 <- a:2 & !c\n",
    "c <- 1\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Rewriting expressions\n",
    "\n",
    "The rewriting of expressions is extended to support node levels in the specification of substitutions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a:1 <- b:1\n",
       "a:2 <- b:1&c\n",
       "b:1 <- a:1\n",
       "b:2 <- a:1&!c\n",
       "c <- 1\n"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "a, b = mvg.vars(\"a\", \"b\")\n",
    "mvg.rewrite(b, {a/2: a/1}) # will rewrite all expressions targetting b\n",
    "mvg"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a:1 <- b:1\n",
       "a:2 <- b:2&c\n",
       "b:1 <- a:1\n",
       "b:2 <- a:1&!c\n",
       "c <- 1\n"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mvg.rewrite(a/2, {b/1: b/2}) # will rewrite only expressions for a:2\n",
    "mvg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Conversion to bioLQM\n",
    "\n",
    "Similarly to `BooleanNetwork` objects, `MultiValuedNetwork` objects have a `to_biolqm` method to convert to bioLQM tool."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "a:1 <- b:1\n",
       "a:2 <- b:1&c\n",
       "b:2 <- a:2|!c\n",
       "b:1 <- a:2&c\n",
       "c <- c&!a:2\n"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mvf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "lqm = mvf.to_biolqm()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "|    |   a |   b |   c |\n",
       "|---:|----:|----:|----:|\n",
       "|  0 |   0 |   0 |   1 |\n",
       "|  1 |   1 |   2 |   0 |"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tabulate(biolqm.fixpoints(lqm))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import bioLQM models\n",
    "\n",
    "The `biolqm.to_minibn` function imports any Boolean/Multi-valued network in the `minibn` interface, enabling programmatic edition of the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Downloading 'http://ginsim.org/sites/default/files/ModelT2DM_0.zginml'"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "lqm = biolqm.load(\"http://ginsim.org/sites/default/files/ModelT2DM_0.zginml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AKT <- (!IRS_PIK3CA&!PTEN&CDK2&!PP2A)|(IRS_PIK3CA&!PTEN&!PP2A)\n",
       "AMPK <- p53&!ATP\n",
       "ATP <- Metabolism\n",
       "CDK2 <- (!p21&mTORC1_S6K1&!MYC&E2F1)|(!p21&mTORC1_S6K1&MYC)\n",
       "E2F1 <- (!GF&MYC&!pRB&E2F1)|(GF&!pRB&E2F1)\n",
       "FOXO <- (!MAPK&!p16&!AKT&!AMPK&Metabolism)|(!MAPK&!p16&!AKT&AMPK)|(!MAPK&p16&!AKT)\n",
       "G1_S <- !p21&CDK2&E2F1&Metabolism\n",
       "GF <- GF\n",
       "IRS_PIK3CA <- Insulin&!mTORC1_S6K1\n",
       "Insulin <- Insulin\n",
       "MAPK <- GF&!PP2A\n",
       "MDM2 <- (!p16&!p53&AKT&!mTORC1_S6K1&!MYC&!E2F1)|(!p16&p53&!mTORC1_S6K1&!MYC&!E2F1)|(p16&!mTORC1_S6K1&!MYC&!E2F1)\n",
       "MYC <- MAPK&!p53&mTORC1_S6K1&E2F1\n",
       "Metabolism <- (!MAPK&!AKT&mTORC1_S6K1&PP1C)|(!MAPK&AKT&mTORC1_S6K1)|(MAPK&!AKT&PP1C)|(MAPK&AKT)\n",
       "PP1C <- (!MAPK&AKT)|MAPK\n",
       "PP2A <- !mTORC1_S6K1\n",
       "PRC <- !AKT&MYC\n",
       "PTEN <- p53&!AKT\n",
       "Senescence <- (!p16&p21&mTORC1_S6K1)|p16\n",
       "TSC <- !MAPK&!AKT&AMPK\n",
       "Therapy <- Therapy\n",
       "mTORC1_S6K1 <- !AMPK&!TSC\n",
       "p16 <- MAPK&!p53&!E2F1&!PRC\n",
       "p21 <- (!p53&!AKT&!MYC&FOXO)|(p53&!AKT&!MYC)\n",
       "p53 <- !MDM2\n",
       "pRB <- !CDK2\n"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f = biolqm.to_minibn(lqm)\n",
    "f"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Downloading 'http://ginsim.org/sites/default/files/phageLambda4.zginml'"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "lqm_mv = biolqm.load(\"http://ginsim.org/sites/default/files/phageLambda4.zginml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "CI:2 <- !Cro|(Cro&CII)\n",
       "CII <- !CI:2&!Cro:3&N\n",
       "Cro:2 <- !CI:2&Cro:3\n",
       "Cro:3 <- !CI:2&!Cro:3\n",
       "N <- !CI&!Cro:2\n"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mv = biolqm.to_minibn(lqm_mv)\n",
    "mv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python3",
   "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.6.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}