examples/example_extended_output.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary of output from model of COVID-19 <a class=\"anchor\" id=\"home\"></a>\n",
    "\n",
    "### Overview\n",
    "\n",
    "This Jupyter notebook summarises output from the [OpenABM-Covid19](https://github.com/BDI-pathogens/OpenABM-Covid19) model.  This notebook provides basic plotting functions for a single simulation of the model using a single set of parameters.  The notebook is intended as a guide for how model output may be explored.  The figures in this notebook demonstrate some of the more detailed outputs from the model including 1) the time series output, 2) summary of all simulated SARS-CoV2 transmission events in a simulated epidemic, and 3) and all interaction events between individuals on the last day of the simulated outbreak.  Model output can be generated using this notebook by evaluating the cells below.  Four larger files generated by the model will be written to file in the location specified in the variable `output_dir` below.  These files are: \n",
    "\n",
    "1. `individual_file_Run1.csv`: a file of all individuals in the simulated epidemic.  \n",
    "2. `transmission_Run1.csv`: a file of all transmission events in the simulated epidemic.  \n",
    "3. `interactions_Run1.csv`: a file of all interaction events on the final day of the simulation.  \n",
    "4. `trace_tokens_Run1.csv`: a file of all contact tracing events (up to the last 14 days) that have not been released.\n",
    "\n",
    "\n",
    "The figures in this notebook are not intended to be used as projections of the current COVID19 outbreak.\n",
    "\n",
    "\n",
    "### Usage\n",
    "\n",
    "1. Download or clone the [OpenABM-Covid19](https://github.com/BDI-pathogens/OpenABM-Covid19) model.  \n",
    "2. Install the Python interface for OpenABM-Covid19 (see the README.md for instructions).  \n",
    "3. Evaluate each of the cells below.  \n",
    "\n",
    "\n",
    "### Table of contents\n",
    "\n",
    "*Output from a single simulation*\n",
    "* [Parameter values and assumptions](#parameter-values-assumptions)\n",
    "* [Time series](#time-series)\n",
    "* [Interactions between individuals](#interactions)\n",
    "* [Transmission network](#transmission-network)\n",
    "* [Age-stratified outputs](#age-stratified-outputs)\n",
    "\n",
    "\n",
    "*Notes*\n",
    "\n",
    "This notebook was generated using the [OpenABM-Covid19](https://github.com/BDI-pathogens/OpenABM-Covid19) codebase 25th May 2020.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import numpy as np, pandas as pd, matplotlib.pyplot as plt\n",
    "from os.path import join\n",
    "from IPython.display import display\n",
    "import plotting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Model parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from COVID19.model import Model, Parameters, ModelParameterException\n",
    "import COVID19.simulation as simulation\n",
    "\n",
    "input_parameter_file = \"../tests/data/baseline_parameters.csv\"\n",
    "parameter_line_number = 1\n",
    "output_dir = \"results\"\n",
    "household_demographics_file = \"../tests/data/baseline_household_demographics.csv\"\n",
    "hospital_file = \"../tests/data/hospital_baseline_parameters.csv\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run model\n",
    "\n",
    "Simulate an epidemic with no interventions for 150 days using a population of 100,000.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "params = Parameters(\n",
    "    input_parameter_file, \n",
    "    parameter_line_number, \n",
    "    output_dir, \n",
    "    household_demographics_file,\n",
    "    hospital_file)\n",
    "\n",
    "T = 150\n",
    "N = 100000\n",
    "params.set_param(\"end_time\", T)\n",
    "params.set_param(\"n_total\", N)\n",
    "\n",
    "model = simulation.COVID19IBM(model = Model(params))\n",
    "sim = simulation.Simulation(env = model, end_time = T)\n",
    "sim.steps(T)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Read input parameter file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_parameters = pd.read_csv(input_parameter_file)\n",
    "\n",
    "# In case any parameter values have been redefined in this Jupyter notebook,\n",
    "# read parameter values from Parameters object\n",
    "df_parameters_used = plotting.get_df_from_params(params, df_parameters.columns)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Write/import output data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Save timeseries data to pandas DataFrame\n",
    "df_timeseries = pd.DataFrame(sim.results)\n",
    "\n",
    "# Write extended output to file\n",
    "sim.env.model.write_output_files()\n",
    "\n",
    "# Import file with information on all individuals\n",
    "df_indiv = pd.read_csv(join(output_dir, \"individual_file_Run1.csv\"))\n",
    "\n",
    "# Import transmission file\n",
    "df_trans = pd.read_csv(join(output_dir, \"transmission_Run1.csv\"))\n",
    "\n",
    "# Import data on interactions in the last day of the simulation\n",
    "df_interact = pd.read_csv(join(output_dir, \"interactions_Run1.csv\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define plotting constants"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from COVID19.model import AgeGroupEnum, EVENT_TYPES, TransmissionTypeEnum\n",
    "\n",
    "interaction_types = [c.value for c in TransmissionTypeEnum ]\n",
    "interaction_labels = [c.name[1:].title() for c in TransmissionTypeEnum]\n",
    "\n",
    "infectious_compartments = [\"PRESYMPTOMATIC\", \"PRESYMPTOMATIC_MILD\", \"ASYMPTOMATIC\", \"SYMPTOMATIC\", \"SYMPTOMATIC_MILD\"]\n",
    "infectious_types = [e.value for e in EVENT_TYPES if e.name in infectious_compartments]\n",
    "infectious_names = [e.name for e in EVENT_TYPES if e.name in infectious_compartments]\n",
    "infectious_labels = [plotting.EVENT_TYPE_STRING[e.value] for e in EVENT_TYPES if e.name in infectious_compartments]\n",
    "\n",
    "# Define age groups and labels <- FIXME: change to Enum in constant.py\n",
    "n_age = len(AgeGroupEnum) + 1\n",
    "age_group_labels = [enum.name[1:].replace(\"_\",\"-\") for enum in AgeGroupEnum]\n",
    "age_group_labels[-1] = \"80+\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Parameter values and assumptions <a class=\"anchor\" id=\"parameter-values-assumptions\"></a>\n",
    "[[Home](#home)]\n",
    "\n",
    "Key parameter values for the simulations below.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df_key_params = pd.DataFrame({\n",
    "    \"Parameter name\": plotting.key_params,\n",
    "    \"Parameter value\": [params.get_param(p) for p in plotting.key_params]\n",
    "})\n",
    "display(df_key_params.style.hide_index().set_precision(4))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Waiting time distributions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [14, 12]\n",
    "fig, ax = plotting.plot_parameter_assumptions(df_parameters_used)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Age-specific parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "age_cols = [\n",
    "    plotting.susceptibility_cols, plotting.asymptomatic_cols,\n",
    "    plotting.hospitalised_cols, plotting.critical_cols,\n",
    "    plotting.fatality_cols, plotting.mild_cols,\n",
    "    plotting.app_users_cols\n",
    "]\n",
    "\n",
    "age_params = [[params.get_param(p) for p in cols] for cols in age_cols]\n",
    "df = pd.DataFrame(age_params); df.columns = age_group_labels\n",
    "df.rename(index = {0:'Relative susceptibility', \n",
    "                   1:'Pr( asymptomatic | infected )',\n",
    "                   2:'Pr( hospitalisation | symptomatic )',\n",
    "                   3:'Pr( ICU | hospitalised )',\n",
    "                   4:'Pr( death | ICU )',\n",
    "                   5:'Pr( mild | infected )',\n",
    "                   6:'Pr( app users )'\n",
    "                  }, inplace = True)\n",
    "display(df.style.set_precision(2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Time series <a class=\"anchor\" id=\"time-series\"></a>\n",
    "[[Home](#home)]\n",
    "\n",
    "Plot the epidemic trajectory and other outputs from the time series file for a single parameter set.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [14, 12]\n",
    "fig, ax = plotting.plot_timeseries_curves(df_timeseries, xlimits = [0, 200])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactions <a class=\"anchor\" id=\"interactions\"></a>\n",
    "[[Home](#home)]\n",
    "\n",
    "Summaries of interactions in the final day of the simulation.  \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [14, 10]\n",
    "# Count interactions for each individual by \"type\" of interaction\n",
    "df_agg = df_interact.groupby([\"ID_1\", \"type\"])[\"ID_1\"].count().reset_index(name = \"count\")\n",
    "\n",
    "# Plot histogram of interaction by network type\n",
    "fig, ax = plotting.plot_hist_by_group(df_agg, groupvar = \"type\", binvar = \"count\", \n",
    "    groups = interaction_types, bins = 25, group_colours = plotting.network_colours, \n",
    "    group_labels = interaction_labels, \n",
    "    xlabel = \"Number of daily connections\", \n",
    "    title = \"Number of daily interactions by network type\", \n",
    "    legend_title = \"Network type\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [14, 10]\n",
    "fig, ax = plotting.plot_interactions_by_age(\n",
    "    df_interact, groupvar = \"age_group_1\", \n",
    "    group_labels = age_group_labels, legend_title = \"Age group\", \n",
    "    title = \"Number of daily interactions by age group\", \n",
    "    xlabel = \"Number of daily connections\", ylabel = \"Count\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "# Transmission network <a class=\"anchor\" id=\"transmission-network\"></a>\n",
    "[[Home](#home)]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Proportion of all transmission from infectious status of source"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remove seed cases\n",
    "df_trans = df_trans[df_trans[\"status_source\"] != EVENT_TYPES.SUSCEPTIBLE.value]\n",
    "\n",
    "# Calculate percent transmissions by disease status of the source\n",
    "percent_trans_status_source = 100*df_trans[\"status_source\"].value_counts()/df_trans.shape[0]\n",
    "percent_trans_status_source = percent_trans_status_source.reset_index()\n",
    "\n",
    "# Summarise DataFrame\n",
    "percent_trans_status_source.columns = [\"status_source\", \"Percent transmissions\"]\n",
    "percent_trans_status_source[\"name\"] = percent_trans_status_source.status_source.map(lambda x: plotting.EVENT_TYPE_STRING[EVENT_TYPES(x).value])\n",
    "\n",
    "display(percent_trans_status_source[percent_trans_status_source[\"Percent transmissions\"] > 0][[\"Percent transmissions\", \"name\"]].style.hide_index().set_precision(2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generation time by infection status of source"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [14, 8]\n",
    "fig, ax = plotting.plot_stacked_hist_by_group(df_trans, \n",
    "    groupvar = \"status_source\", binvar = \"generation_time\", \n",
    "    groups = infectious_types,\n",
    "    NBINS = 18, group_labels = infectious_labels,\n",
    "    xlabel = \"Generation time\", ylabel = \"Count\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transmission events by age of infected individual and location of infection event"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [16, 10]\n",
    "fig, ax = plotting.plot_hist_by_group(df_trans[df_trans.infector_network >= 0], \n",
    "    groupvar = \"infector_network\", binvar = \"age_group_recipient\", \n",
    "    groups = [0, 1, 2], bins = n_age, group_colours = plotting.network_colours,\n",
    "    group_labels = interaction_labels, \n",
    "    xlabel = \"Age group of infected individual\",ylabel = \"Count\",\n",
    "    title = \"Transmission events by age and network type\",\n",
    "    legend_title = \"Network type\", xticklabels = age_group_labels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Transmission events stratified by age\n",
    "\n",
    "Of all transmission events, the following figure shows the distribution of transmission events (2D histogram) stratified by the age of the source and recipient.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "fig, ax = plotting.plot_transmission_heatmap_by_age(df_trans, \"age_group_recipient\", \"age_group_source\", \n",
    "    bins = n_age, xlabel = \"Age of recipient\", ylabel = \"Age of source\", legend_title = \"Number of transmission events\",\n",
    "    xticklabels = age_group_labels, yticklabels = age_group_labels)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [16, 8]\n",
    "fig, ax = plotting.transmission_heatmap_by_age_by_panels(\n",
    "    df_trans, \"age_group_recipient\", \"age_group_source\", bins = n_age, \n",
    "    panelvar = \"infector_network\", panel_labels = interaction_labels,\n",
    "    xlabel = \"Age of recipient\", ylabel = \"Age of source\", \n",
    "    legend_title = \"Number of\\ntransmission events\",\n",
    "    xticklabels = age_group_labels, yticklabels = age_group_labels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Age-stratified outputs <a class=\"anchor\" id=\"age-stratified-outputs\"></a>\n",
    "\n",
    "States that an individual may be in, stratified by age (of all individuals ever in such a state in the simulation).  \n",
    "\n",
    "[[Home](#home)]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [16, 16]\n",
    "groupvars = [\"time_infected\", \"time_recovered\", \"time_death\"]\n",
    "labels = [\"Infected\", \"Recovered\", \"Deaths\"]\n",
    "\n",
    "fig, ax = plotting.PlotHistByAge(df_trans, groupvars = groupvars, group_labels = labels,\n",
    "    NBINS = n_age -1 , density = True, xticklabels = age_group_labels, xlabel = \"Age group\",\n",
    "    ylim = 0.5, age_group_var = \"age_group_recipient\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [16, 16]\n",
    "groupvars = [\"time_asymptomatic\", \"time_presymptomatic_mild\", \"time_presymptomatic_severe\", \"time_symptomatic_mild\", \"time_symptomatic_severe\"]\n",
    "labels = [\"Asymptomatic\", \"Pre-symptomatic mild\", \"Pre-symptomatic severe\", \"Symptomatic mild\", \"Symptomatic severe\"]\n",
    "fig, ax = plotting.PlotHistByAge(df_trans, groupvars = groupvars, group_labels = labels,\n",
    "    NBINS = n_age -1 , density = True, xticklabels = age_group_labels, xlabel = \"Age group\",\n",
    "    ylim = 0.25, age_group_var = \"age_group_recipient\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [16, 16]\n",
    "groupvars = [\"time_hospitalised\", \"time_critical\"]\n",
    "labels = [\"Hospitalisations\", \"ICU\"]\n",
    "\n",
    "fig, ax = plotting.PlotHistByAge(df_trans, groupvars = groupvars, group_labels = labels,\n",
    "    NBINS = n_age -1 , density = True, xticklabels = age_group_labels, xlabel = \"Age group\",\n",
    "    ylim = 0.5, age_group_var = \"age_group_recipient\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plt.rcParams['figure.figsize'] = [12, 8]\n",
    "fig, ax = plotting.PlotHistIFRByAge(df_trans, \"time_death\", \"time_infected\", NBINS = n_age -1, \n",
    "    xticklabels = age_group_labels, xlabel = \"Age group\", age_group_var = \"age_group_recipient\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}