{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# API Features\n", "\n", "This notebook demonstrates the new API features added in epimodels v0.5.3:\n", "\n", "- `to_dataframe()` - Export results to pandas DataFrame\n", "- `to_dict()` - Get a copy of simulation traces\n", "- `summary()` - Get epidemic summary statistics\n", "- `copy()` - Create a copy of the model\n", "- `reset()` - Clear simulation results\n", "- `R0` property - Basic reproduction number\n", "- Parameter validation" ] }, { "cell_type": "code", "metadata": { "ExecuteTime": { "end_time": "2026-03-09T17:45:03.177290912Z", "start_time": "2026-03-09T17:45:03.117223546Z" } }, "source": [ "from epimodels.continuous import SIR, SIS, SEIR, SIRS\n", "from epimodels.discrete import SIR as DiscreteSIR\n", "from epimodels import ValidationError\n", "import matplotlib.pyplot as plt" ], "outputs": [], "execution_count": 1 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic Reproduction Number (R0)\n", "\n", "The R0 property returns the basic reproduction number for the model. It's calculated from the model parameters after running a simulation." ] }, { "cell_type": "code", "metadata": { "ExecuteTime": { "end_time": "2026-03-09T17:40:08.685831613Z", "start_time": "2026-03-09T17:40:07.508975915Z" } }, "source": [ "model = SIR()\n", "\n", "# R0 is None before running the model\n", "print(f\"R0 before simulation: {model.R0}\")\n", "\n", "# Run the model\n", "model([1000, 1, 0], [0, 100], 1001, {'beta': 0.3, 'gamma': 0.1})\n", "\n", "# Now R0 is available (beta/gamma = 3.0)\n", "print(f\"R0 after simulation: {model.R0}\")" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "R0 before simulation: None\n", "R0 after simulation: 2.9999999999999996\n" ] } ], "execution_count": 2 }, { "cell_type": "markdown", "metadata": {}, "source": [ "### R0 for different models\n", "\n", "The R0 property is available for SIR, SIS, SEIR, and SIRS models." ] }, { "cell_type": "code", "metadata": { "ExecuteTime": { "end_time": "2026-03-09T17:40:30.431659477Z", "start_time": "2026-03-09T17:40:30.336165056Z" } }, "source": [ "# SIS model\n", "sis = SIS()\n", "sis([1000, 1], [0, 50], 1001, {'beta': 0.5, 'gamma': 0.25})\n", "print(f\"SIS R0: {sis.R0}\")\n", "\n", "# SEIR model\n", "seir = SEIR()\n", "seir([1000, 0, 1, 0], [0, 50], 1001, {'beta': 0.4, 'gamma': 0.2, 'epsilon': 0.1})\n", "print(f\"SEIR R0: {seir.R0}\")\n", "\n", "# SIRS model\n", "sirs = SIRS()\n", "sirs([1000, 1, 0], [0, 50], 1001, {'beta': 0.6, 'gamma': 0.3, 'xi': 0.05})\n", "print(f\"SIRS R0: {sirs.R0}\")" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "SIS R0: 2.0\n", "SEIR R0: 2.0\n", "SIRS R0: 2.0\n" ] } ], "execution_count": 3 }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Summary Statistics\n", "\n", "The `summary()` method returns key epidemic statistics from the simulation." ] }, { "cell_type": "code", "metadata": { "ExecuteTime": { "end_time": "2026-03-09T17:40:46.078554213Z", "start_time": "2026-03-09T17:40:45.939802842Z" } }, "source": [ "model = SIR()\n", "model([1000, 1, 0], [0, 100], 1001, {'beta': 0.3, 'gamma': 0.1})\n", "\n", "stats = model.summary()\n", "print(\"Epidemic Summary:\")\n", "for key, value in stats.items():\n", " print(f\" {key}: {value:.2f}\" if isinstance(value, float) else f\" {key}: {value}\")" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Epidemic Summary:\n", " model: SIR\n", " t_start: 0.00\n", " t_end: 100.00\n", " peak_I: 298.70\n", " peak_time: 37.05\n", " final_S: 60.75\n", " final_R: 936.14\n", " attack_rate: 0.94\n" ] } ], "execution_count": 4 }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Understanding the statistics\n", "\n", "- **peak_I**: Maximum number of infectious individuals\n", "- **peak_time**: Time at which peak I occurs\n", "- **final_S**: Final susceptible count\n", "- **final_R**: Final removed (recovered) count\n", "- **attack_rate**: Proportion of population that was infected" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Export to DataFrame\n", "\n", "The `to_dataframe()` method exports simulation results to a pandas DataFrame for easy analysis." ] }, { "cell_type": "code", "metadata": { "ExecuteTime": { "end_time": "2026-03-02T18:12:19.768770387Z", "start_time": "2026-03-02T18:12:19.245498152Z" } }, "source": [ "model = SIR()\n", "model([1000, 1, 0], [0, 50], 1001, {'beta': 0.3, 'gamma': 0.1})\n", "\n", "df = model.to_dataframe()\n", "print(f\"DataFrame shape: {df.shape}\")\n", "print(f\"Columns: {list(df.columns)}\")\n", "df.head()" ], "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "DataFrame shape: (10, 4)\n", "Columns: ['S', 'I', 'R', 'time']\n" ] }, { "data": { "text/plain": [ " S I R time\n", "0 1000.000000 1.000000 0.000000 0.000000\n", "1 999.995758 1.002827 0.001416 0.014135\n", "2 999.952671 1.031536 0.015792 0.155485\n", "3 999.447946 1.367801 0.184253 1.568989\n", "4 996.610788 3.256427 1.132785 5.924102" ], "text/html": [ "
| \n", " | S | \n", "I | \n", "R | \n", "time | \n", "
|---|---|---|---|---|
| 0 | \n", "1000.000000 | \n", "1.000000 | \n", "0.000000 | \n", "0.000000 | \n", "
| 1 | \n", "999.995758 | \n", "1.002827 | \n", "0.001416 | \n", "0.014135 | \n", "
| 2 | \n", "999.952671 | \n", "1.031536 | \n", "0.015792 | \n", "0.155485 | \n", "
| 3 | \n", "999.447946 | \n", "1.367801 | \n", "0.184253 | \n", "1.568989 | \n", "
| 4 | \n", "996.610788 | \n", "3.256427 | \n", "1.132785 | \n", "5.924102 | \n", "