Zombie-Apocalypse-PySB.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "373e1f02",
   "metadata": {},
   "source": [
    "# Modeling a Zombie Apocalypse in PySB\n",
    "\n",
    "## Credits\n",
    "* Zombie Apocalypse example by [Munz et al. 2009](https://mysite.science.uottawa.ca/rsmith43/Zombies.pdf)\n",
    "* SciPy implementation by [Christopher Campo](https://scipy-cookbook.readthedocs.io/items/Zombie_Apocalypse_ODEINT.html)\n",
    "* Jupyter Notebook interactivity and PySB conversion by Alex Lubbock\n",
    "\n",
    "## Background\n",
    "\n",
    "This example demonstrates how to solve a system of first order ordinary differential equations (ODEs) using [PySB](https://pysb.org). In this lighthearted example, a system of ODEs can be used to model a \"zombie invasion\", using the equations specified in Munz et al. 2009.\n",
    "\n",
    "### Quick recap on differential equations\n",
    "\n",
    "Remember from calculus that the _derivative_ of a function gives its rate of change (obtained by _differentiation_). Conversely, we can _integrate_ that derivative to get back to the original function. In the case of simple functions, this can be solved analytically (calculus). However, for more complex equations or even sets of equations, analytical solutions are intractable. Thus, we can solve the system numerically - the computer provides an approximate solution by stepping through the function over time. The most common case is for _ordinary differential equations_ or _ODEs_, which consist of one or more equations for one variable at a time (contrast with _partial differential equations_, which contain multiple variables).\n",
    "\n",
    "### Modelling using ODEs\n",
    "\n",
    "Typically, we know equations for the rates of change for some entities and want to \"solve\" the system (get the number of those entities over time). We do this using an _integrator_, in this case we'll use the SciPy integrator, to conduct a simulation.\n",
    "\n",
    "Some examples include:\n",
    "\n",
    " * Biochemical simulations, where we start with some reactants and equations that define how they react (bind, unbind, catalyse etc.) over time\n",
    " * Predator/prey models, where predator and prey reproduce, die, and the predator eat the prey\n",
    " * A zombie apocalypse, where people can turn into zombies and infect others\n",
    " \n",
    "A PySB model consists of a few components:\n",
    "\n",
    " * *Species* - the components or entities being modelled as a continuous variable\n",
    " * *Parameters*, consisting of\n",
    "   - *Initial conditions* - the initial numbers of those species at the start of a simulation\n",
    "   - *Rate parameters* - values which affect how fast species convert into each other\n",
    " * *Reaction rules* - a set of rules showing how species evolve over time\n",
    " * *Time range* - a time period to simulate over\n",
    " * *Observables* - the output quantities of interest from the model (typically, all or a subset of the species)\n",
    " \n",
    "In PySB, we specify reaction rules rather than ODEs directly. Note that reaction rules and ODEs are equivalent, but in more complex systems reaction rules are easier to specify than ODEs directly.\n",
    " \n",
    "## A model of zombie infection\n",
    "\n",
    "![asdf](model-diagram.png)\n",
    "\n",
    "Populations (the \"species\" of the model, represented as `Monomers` in the PySB framework):\n",
    "\n",
    "    Susceptible (S): the number of susceptible victims\n",
    "    Zombie (Z): the number of zombies\n",
    "    Removed (R): the number of people \"killed\"\n",
    "    \n",
    "Parameters:\n",
    "\n",
    "    k_birth (π in the figure above): the population birth rate\n",
    "    k_death (δ in the figure above): the chance of a natural death\n",
    "    k_infect (β in the figure above): the chance the \"zombie disease\" is transmitted (an alive person becomes a zombie)\n",
    "    k_resurrect (γ in the figure above): the chance a dead person is resurrected into a zombie\n",
    "    k_destroy (α in the figure above): the chance a zombie is totally destroyed\n",
    "\n",
    "This involves solving a system of first order ODEs given by: dy/dt = f(y, t). However, using PySB, the system can be given as a set of reaction rules and the underlying ODE system is solved at runtime. This representation is typically clearer and easier to update and maintain.\n",
    "\n",
    "## How to run this notebook\n",
    "\n",
    "Select the **Kernel** menu at the top of the page, then select **Restart & Run All**. After a few seconds, a plot should appear at the bottom of the page."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec06ccba",
   "metadata": {},
   "source": [
    "## Step 1: Import required libraries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d78695bd",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Enable inline plots in Jupyter Notebook (i.e. show graphics here, in the notebook, rather than writing to a file)\n",
    "%matplotlib inline\n",
    "\n",
    "# Import required libraries\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib.widgets import Slider\n",
    "from pysb import Model, Monomer, Parameter, Initial, Rule\n",
    "from pysb.simulator import ScipyOdeSimulator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36917dff",
   "metadata": {},
   "source": [
    "## Step 2: Define the model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0677f8cc",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an empty model\n",
    "Model()\n",
    "\n",
    "# Default parameter values\n",
    "Parameter('k_birth', 0)       # birth rate\n",
    "Parameter('k_death', 0.0001)  # natural death rate (per day)\n",
    "Parameter('k_infect', 0.0095)  # transmission rate  (per day)\n",
    "Parameter('k_resurrect', 0.0001)  # resurrect rate (per day)\n",
    "Parameter('k_destroy', 0.0001)  # destroy rate  (per day)\n",
    "\n",
    "# Our \"monomers\" are our types of individual\n",
    "# Analagous to chemical species in a reaction model\n",
    "Monomer('Susceptible')\n",
    "Monomer('Zombie')\n",
    "Monomer('Removed')\n",
    "\n",
    "# Initial conditions\n",
    "Initial(Susceptible(), Parameter('S_0', 500))    # initial population\n",
    "Initial(Zombie(), Parameter('Z_0', 0))           # initial zombie population\n",
    "Initial(Removed(), Parameter('R_0', 0))          # initial death population\n",
    "\n",
    "# Reaction rules\n",
    "Rule('r_birth', None >> Susceptible(), k_birth)\n",
    "Rule('r_death', Susceptible() >> Removed(), k_death)\n",
    "Rule('r_infected', Susceptible() + Zombie() >> Zombie() + Zombie(), k_infect)\n",
    "Rule('r_destroy', Susceptible() + Zombie() >> Susceptible() + Removed(), k_destroy)\n",
    "Rule('r_resurrect', Removed() >> Zombie(), k_resurrect)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "87b8e400",
   "metadata": {},
   "source": [
    "## Step 3: Run the simulation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a898245",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Time vector (0 to 3 days, 1000 steps)\n",
    "tspan = np.linspace(0, 3, 1000)\n",
    "\n",
    "# Create the simulator\n",
    "sim = ScipyOdeSimulator(model, tspan)\n",
    "\n",
    "# Run the simulation\n",
    "soln = sim.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5a0a276",
   "metadata": {},
   "source": [
    "## Step 4: Plot the results"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c172c9d7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Plot results\n",
    "fig, ax = plt.subplots()\n",
    "l1, = plt.plot(tspan, soln.species[:, 0], label='Living')\n",
    "l2, = plt.plot(tspan, soln.species[:, 1], label='Zombies')\n",
    "plt.xlabel('Days from outbreak')\n",
    "plt.ylabel('Population')\n",
    "plt.title('Zombie Apocalypse')\n",
    "plt.legend(loc=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "23baff8d",
   "metadata": {},
   "source": [
    "## Step 5: Further exercises\n",
    "\n",
    "1. Try changing the simulation time from 3 to 28 days later. Does the outcome look different? (To re-run the notebook, select **Kernel** then **Restart & Run All** from the menu bar).\n",
    "2. Try altering the model parameters to see what it would take to fight off the zombies - increase the birth rate? increase the destroy rate?\n",
    "3. (Advanced) Refer to the [Munz et al. 2009](https://mysite.science.uottawa.ca/rsmith43/Zombies.pdf) for extensions to the model, including adding a latent infection and a quarantine system."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}