From 91d0e0ec20ecd17af4bf230aa1ad64a987b6e0a8 Mon Sep 17 00:00:00 2001 From: Adish Assain Date: Wed, 9 Sep 2026 10:30:35 +0200 Subject: [PATCH] docs: add research impact statement and cite closest tools Add the Research impact statement section required by the JOSS paper format. Cite the metapopulation frameworks closest to PatchSim (flepiMoP, MetaCast, SimInf, MetaWards, MEmilio) and state why none was extended. Cite the use cases named in the Statement of need, describe the coupling form in Software design with its primary references, state the deterministic limitation, and add the Sobol method citation. --- paper.bib | 239 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- paper.md | 134 ++++++++++++++++++++++-------- 2 files changed, 335 insertions(+), 38 deletions(-) diff --git a/paper.bib b/paper.bib index 99ff667..c56f1bf 100644 --- a/paper.bib +++ b/paper.bib @@ -10,8 +10,9 @@ @misc{patchsim } @misc{VenkatramananPatchSim, - author = {Venkatramanan, Srinivasan and Chen, Jiangzhuo and Marathe, Madhav}, - title = {{PatchSim}: code for simulating the metapopulation {SEIR} model}, + author = {Venkatramanan, Srini and Bhattacharya, Parantapa and Porebski, Przemek and + Klahn, Brian}, + title = {{NSSAC/PatchSim}: First official release}, year = {2020}, publisher = {Zenodo}, version = {v1.0}, @@ -53,7 +54,7 @@ @misc{Adiga2021 Madhav V. and Rathod, Nihesh and Sundaresan, Rajesh and Swarup, Samarth and Venkatramanan, Srinivasan and Yasodharan, Sarath}, title = {Strategies to Mitigate {COVID-19} Resurgence Assuming Immunity Waning: - A Study for Karnataka, India}, + A Study for {Karnataka, India}}, publisher = {medRxiv}, year = {2021}, type = {Preprint}, @@ -117,8 +118,7 @@ @article{Hladish2012 @article{Maier2021, author = {Maier, Benjamin F.}, - title = {Epipack: An open-source {Python} package for epidemiological - compartmental models}, + title = {epipack: An infectious disease modeling package for {Python}}, journal = {Journal of Open Source Software}, year = {2021}, volume = {6}, @@ -165,3 +165,232 @@ @article{Jenness2018 pages = {1--47}, doi = {10.18637/jss.v084.i08} } + +@article{Keeling2001, + author = {Keeling, Matt J. and Woolhouse, Mark E. J. and Shaw, Darren J. and + Matthews, Louise and Chase-Topping, Margo and Haydon, Dan T. and + Cornell, Stephen J. and Kappey, Jens and Wilesmith, John and + Grenfell, Bryan T.}, + title = {Dynamics of the 2001 {UK} foot and mouth epidemic: stochastic dispersal + in a heterogeneous landscape}, + journal = {Science}, + year = {2001}, + volume = {294}, + number = {5543}, + pages = {813--817}, + doi = {10.1126/science.1065973} +} + +@article{Tildesley2006, + author = {Tildesley, Michael J. and Savill, Nicholas J. and Shaw, Darren J. and + Deardon, Rob and Brooks, Stephen P. and Woolhouse, Mark E. J. and + Grenfell, Bryan T. and Keeling, Matt J.}, + title = {Optimal reactive vaccination strategies for a foot-and-mouth outbreak + in the {UK}}, + journal = {Nature}, + year = {2006}, + volume = {440}, + number = {7080}, + pages = {83--86}, + doi = {10.1038/nature04324} +} + +@article{GuyverFletcher2025, + author = {Guyver-Fletcher, Glen and Gorsich, Erin E. and Jewell, Chris and + Tildesley, Michael J.}, + title = {Controlling endemic foot-and-mouth disease: vaccination is more + important than movement bans. {A} simulation study in the + {Republic of Turkey}}, + journal = {Infectious Disease Modelling}, + year = {2025}, + volume = {10}, + number = {2}, + pages = {702--715}, + doi = {10.1016/j.idm.2025.02.006} +} + +@article{Wesolowski2015, + author = {Wesolowski, Amy and Qureshi, Taimur and Boni, Maciej F. and + Sunds{\o}y, P{\aa}l Roe and Johansson, Michael A. and + Rasheed, Syed Basit and Eng{\o}-Monsen, Kenth and Buckee, Caroline O.}, + title = {Impact of human mobility on the emergence of dengue epidemics in + {Pakistan}}, + journal = {Proceedings of the National Academy of Sciences}, + year = {2015}, + volume = {112}, + number = {38}, + pages = {11887--11892}, + doi = {10.1073/pnas.1504964112} +} + +@article{Gatto2020, + author = {Gatto, Marino and Bertuzzo, Enrico and Mari, Lorenzo and + Miccoli, Stefano and Carraro, Luca and Casagrandi, Renato and + Rinaldo, Andrea}, + title = {Spread and dynamics of the {COVID-19} epidemic in {Italy}: effects of + emergency containment measures}, + journal = {Proceedings of the National Academy of Sciences}, + year = {2020}, + volume = {117}, + number = {19}, + pages = {10484--10491}, + doi = {10.1073/pnas.2004978117} +} + +@article{Gunasekera2022, + author = {Gunasekera, Umanga and Biswal, Jitendra Kumar and Machado, Gustavo and + Ranjan, Rajeev and Subramaniam, Saravanan and Rout, Manoranjan and + Mohapatra, Jajati Keshari and Pattnaik, Bramhadev and + Singh, Rabindra Prasad and Arzt, Jonathan and Perez, Andres and + VanderWaal, Kimberly}, + title = {Impact of mass vaccination on the spatiotemporal dynamics of {FMD} + outbreaks in {India}, 2008--2016}, + journal = {Transboundary and Emerging Diseases}, + year = {2022}, + volume = {69}, + number = {5}, + pages = {e1936--e1950}, + doi = {10.1111/tbed.14528} +} + +@article{Balcan2010, + author = {Balcan, Duygu and Gon{\c{c}}alves, Bruno and Hu, Hao and + Ramasco, Jos{\'e} J. and Colizza, Vittoria and Vespignani, Alessandro}, + title = {Modeling the spatial spread of infectious diseases: the {GLobal Epidemic + and Mobility} computational model}, + journal = {Journal of Computational Science}, + year = {2010}, + volume = {1}, + number = {3}, + pages = {132--145}, + doi = {10.1016/j.jocs.2010.07.002} +} + +@article{Woods2022, + author = {Woods, Christopher and Hedges, Lester and Edsall, Christopher and + Brooks-Pollock, Ellen and Parton-Fenton, Christopher and + McKinley, Trevelyan and Keeling, Matt and Danon, Leon}, + title = {{MetaWards}: a flexible metapopulation framework for modelling disease + spread}, + journal = {Journal of Open Source Software}, + year = {2022}, + volume = {7}, + number = {70}, + pages = {3914}, + doi = {10.21105/joss.03914} +} + +@article{Bicker2026, + author = {Bicker, Julia and Gerstein, Carlotta and Kerkmann, David and + Korf, Sascha and Schmieding, Ren{\'e} and Wendler, Anna and others}, + title = {{MEmilio}: a high performance modular epidemics simulation software + for multi-scale and comparative simulations of infectious disease + dynamics}, + journal = {Scientific Reports}, + year = {2026}, + volume = {16}, + number = {1}, + pages = {26950}, + doi = {10.1038/s41598-026-66481-6} +} + +@article{Widgren2019, + author = {Widgren, Stefan and Bauer, Pavol and Eriksson, Robin and + Engblom, Stefan}, + title = {{SimInf}: an {R} package for data-driven stochastic disease spread + simulations}, + journal = {Journal of Statistical Software}, + year = {2019}, + volume = {91}, + number = {12}, + pages = {1--42}, + doi = {10.18637/jss.v091.i12} +} + +@article{Grunnill2024, + author = {Grunnill, Martin and Arino, Julien and Ghasemi, Abbas and + Thommes, Edward W. and Wu, Jianhong}, + title = {{MetaCast}: a package for {broadCASTing} epidemiological and + ecological models over {META}-populations}, + journal = {Journal of Open Source Software}, + year = {2024}, + volume = {9}, + number = {99}, + pages = {6851}, + doi = {10.21105/joss.06851} +} + +@article{Lemaitre2024, + author = {Lemaitre, Joseph C. and Loo, Sara L. and Kaminsky, Joshua and + Lee, Elizabeth C. and McKee, Clifton and Smith, Claire and + Jung, Sung-mok and Sato, Koji and Carcelen, Erica and Hill, Alison and + Lessler, Justin and Truelove, Shaun}, + title = {{flepiMoP}: the evolution of a flexible infectious disease modeling + pipeline during the {COVID-19} pandemic}, + journal = {Epidemics}, + year = {2024}, + volume = {47}, + pages = {100753}, + doi = {10.1016/j.epidem.2024.100753} +} + +@article{Sattenspiel1995, + author = {Sattenspiel, Lisa and Dietz, Klaus}, + title = {A structured epidemic model incorporating geographic mobility among + regions}, + journal = {Mathematical Biosciences}, + year = {1995}, + volume = {128}, + number = {1--2}, + pages = {71--91}, + doi = {10.1016/0025-5564(94)00068-B} +} + +@article{Citron2021, + author = {Citron, Daniel T. and Guerra, Carlos A. and Dolgert, Andrew J. and + Wu, Sean L. and Henry, John M. and S{\'a}nchez C., H{\'e}ctor M. and + Smith, David L.}, + title = {Comparing metapopulation dynamics of infectious diseases under + different models of human movement}, + journal = {Proceedings of the National Academy of Sciences}, + year = {2021}, + volume = {118}, + number = {18}, + pages = {e2007488118}, + doi = {10.1073/pnas.2007488118} +} + +@article{Riley2007, + author = {Riley, Steven}, + title = {Large-scale spatial-transmission models of infectious disease}, + journal = {Science}, + year = {2007}, + volume = {316}, + number = {5829}, + pages = {1298--1301}, + doi = {10.1126/science.1134695} +} + +@article{Ball2015, + author = {Ball, Frank and Britton, Tom and House, Thomas and Isham, Valerie and + Mollison, Denis and Pellis, Lorenzo and Scalia Tomba, Gianpaolo}, + title = {Seven challenges for metapopulation models of epidemics, including + households models}, + journal = {Epidemics}, + year = {2015}, + volume = {10}, + pages = {63--67}, + doi = {10.1016/j.epidem.2014.08.001} +} + +@article{Sobol2001, + author = {{Sobol'}, Ilya M.}, + title = {Global sensitivity indices for nonlinear mathematical models and their + {Monte Carlo} estimates}, + journal = {Mathematics and Computers in Simulation}, + year = {2001}, + volume = {55}, + number = {1--3}, + pages = {271--280}, + doi = {10.1016/S0378-4754(00)00270-6} +} diff --git a/paper.md b/paper.md index 20a7db3..afd61b9 100644 --- a/paper.md +++ b/paper.md @@ -32,8 +32,10 @@ approach in which a landscape is partitioned into discrete geographical units (patches) — such as subdistricts, districts, or ecological zones — connected by a weighted contact network. Within each patch, disease progression is described by user-defined compartmental models (e.g., SIR, SEIR, SIRS) -specified through a YAML configuration file using a declarative arrow-map transition -syntax. PatchSim provides adaptive ODE and explicit-Euler solvers, Sobol sensitivity +specified in a YAML configuration file, where each transition is written as +`source -> target` with a rate expression. PatchSim provides adaptive ordinary +differential equation (ODE) and +explicit-Euler solvers, Sobol sensitivity analysis via SALib [@Herman2017], bounded least-squares calibration, and command-line and Python interfaces. Its configuration-first scope covers compartment-transfer models over supplied patch and group interaction data; scientific assumptions remain the @@ -45,35 +47,43 @@ source code and documentation linked from the project record [@patchsim]. Mathematical modelling of infectious diseases is essential for understanding transmission dynamics, evaluating interventions, and informing public health policy [@Keeling2008]. Metapopulation models — which capture the heterogeneity of disease -spread across connected spatial units — are particularly valuable for diseases where -population movement shapes outbreak trajectories, including foot-and-mouth disease in -livestock, dengue in urban landscapes, and respiratory infections across administrative -regions [@Grenfell1997; @Balcan2009]. +spread across connected spatial units [@Grenfell1997] — are particularly valuable for +diseases where population movement shapes outbreak trajectories, including +foot-and-mouth disease in livestock [@Keeling2001; @Tildesley2006; @GuyverFletcher2025], +dengue in urban landscapes [@Wesolowski2015], and respiratory infections across +administrative regions [@Balcan2009; @Gatto2020]. Implementing such models commonly requires custom scientific code or a platform tied to a particular modelling abstraction. This adds software work to the scientific tasks of specifying transitions, preparing spatial inputs, and checking model assumptions. -PatchSim addresses this gap through a configuration-first design in which model +PatchSim reduces this cost through a configuration-first design in which model structure — compartments, transitions, and parameters — is declared in a YAML file rather than implemented in code. The intended users are epidemiological modellers, researchers studying spatial disease dynamics, and public health analysts who need to rapidly prototype and compare scenarios across spatial configurations and disease -systems. PatchSim was developed at ARTPARK, IISc, to support active modelling work on -livestock disease dynamics in India. The current package is used locally for ongoing -foot-and-mouth disease vaccination-scenario analysis across Karnataka districts, -replacing an earlier project-specific implementation; the workflow models cattle and -buffalo populations stratified by age group and species. +systems. PatchSim was developed at ARTPARK, the AI and Robotics Technology Park at the +Indian Institute of Science (IISc), to support active modelling work on livestock +disease dynamics in India. # State of the field Existing software spans several related abstractions: EpiFire [@Hladish2012] and EpiModel [@Jenness2018] address contact-network epidemiology; epipack [@Maier2021] supports compartmental, stochastic, and network models; EMOD [@Bershteyn2018] uses an -individual-based architecture; and GLEaMviz [@VandenBroeck2011] represents global -mobility-driven metapopulations. PatchSim instead centres a configuration-defined -compartment system over a user-supplied weighted patch matrix and optional categorical -group interactions. +individual-based architecture; and GLEaM [@Balcan2010; @VandenBroeck2011] represents +global mobility-driven metapopulations. + +Metapopulation frameworks closer to PatchSim +include MetaWards [@Woods2022], MEmilio [@Bicker2026], SimInf [@Widgren2019], MetaCast +[@Grunnill2024], and flepiMoP [@Lemaitre2024]. MetaWards is a stochastic metapopulation +framework originally built for the electoral wards of Great Britain. MEmilio is a C++ +core with Python bindings that offers graph-ODE and agent-based models. SimInf declares +stochastic transitions as strings over nodes +linked by scheduled livestock movements. MetaCast broadcasts a user-written Python ODE +over subpopulations and bundles Latin hypercube sensitivity analysis. flepiMoP is an R +and Python forecasting pipeline that declares compartments and transitions in YAML over +a mobility matrix. PatchSim is an independent implementation, but it shares both its name and its modelling lineage with an earlier package developed at the Network Systems Science and @@ -94,16 +104,30 @@ name is retained to acknowledge this lineage. The earlier implementation is dist as `NSSAC/PatchSim`; this package is distributed as `patchsim` from `dsih-artpark/patchsim`. -PatchSim is a lightweight, configuration-first Python framework for geographic -metapopulation modelling with user-defined compartmental transitions. A modeller can -switch between supported compartment structures, solvers, spatial networks, and group -interaction inputs without rewriting the runtime. +We did not build on the three closest tools for the following reasons. flepiMoP already +declares compartments and transitions in YAML over a mobility matrix and offers a +deterministic solver. At the time of writing it lacks variance-based sensitivity +indices and bounded least-squares calibration, fits by Markov chain Monte Carlo, and +its R and Python pipeline is larger than the single package the Karnataka work needed. +MetaCast +expresses the model as Python code, so a change in compartments is a code change. +SimInf is stochastic only and moves animals by scheduled events rather than through a +contact matrix, so it does not provide the deterministic comparison over district +contact data that the Karnataka work needed. + +PatchSim contributes the combination none of the three offers in one Python package +with a command-line interface: a compartment +graph and rate expressions declared in configuration, a user-supplied weighted patch +matrix, categorical group stratification, a deterministic solver, Sobol sensitivity +analysis, and bounded calibration. A modeller can switch between compartment +structures, solvers, spatial networks, and group interaction inputs without rewriting +the runtime. # Software design PatchSim's central design principle is that compartmental model structure is declared -in YAML rather than implemented in code. Transitions are expressed as arrow-map -expressions pairing source and target compartments with a rate formula: +in YAML rather than implemented in code. Transitions are written as +`source -> target` keys, each paired with a rate formula: ```yaml compartments: [S, I, R] @@ -113,29 +137,73 @@ Transitions: "I -> R": "gamma * I" ``` -For focal patch $i$, the infectious pressure is -$\lambda_i(t)=\sum_j W_{ij}I_j(t)/N_j(t)$; the infection flow in this example is -$\beta S_i\lambda_i$. PatchSim does not normalize the supplied weights. ODE mode uses -`scipy.integrate.odeint`, SciPy's interface to LSODA, while discrete mode uses -deterministic explicit Euler. Both evaluate the same derivative function; discrete -results should be checked at successively smaller time steps. The current network is -fixed from day zero. Patch populations, initial states, network weights, and optional -group interactions are read from CSV files resolved relative to the configuration. +A rate expression that does not name its source compartment is multiplied by that +compartment, so `"S -> I": "beta"` gives a local flow of $\beta S_i$. For focal patch +$i$ in an ungrouped multi-patch model, the infectious pressure is +$\lambda_i(t)=\sum_j W_{ij}I_j(t)/N_j$, and the infection flow in this example is +$\beta S_i\lambda_i$; a single ungrouped patch applies no coupling, and grouped models +also multiply by the group interaction matrix. This is a residence-based +coupling in the sense of the Lagrangian multi-patch models of @Sattenspiel1995 and +@Citron2021. Patch populations stay fixed at $N_i$, and residents of patch $i$ are +exposed to the resident prevalence of each patch $j$ in proportion to $W_{ij}$; no +population moves. The prevalence at patch $j$ counts residents only, whereas the full +Sattenspiel–Dietz model counts visiting infectives and visitors in both numerator and +denominator. + +A supplied $W$ is applied as given and its rows are not normalized, so the scale of $W$ +multiplies $\beta$. The built-in contact-network generator can produce row-normalized +weights with a self-share diagonal. Whether a supplied matrix should do the same, and +whether it comes from a gravity kernel or observed movement data, is the modeller's +choice. The spatial coupling is bound to the compartment names `S`, `I`, and `E`, and +$\lambda_i$ counts `I` alone. + +ODE mode uses `scipy.integrate.odeint`, SciPy's interface to the LSODA solver, while +discrete mode uses deterministic explicit Euler. Both evaluate the same derivative function; discrete +results should be checked at successively smaller time steps. As a deterministic patch +model, PatchSim does not represent stochastic fade-out or invasion probability in small +patches [@Riley2007; @Ball2015]. The current network is fixed from day zero. Patch +populations, initial states, network weights, and optional group interactions are read +from CSV files resolved relative to the configuration. Validation checks required fields, identifiers, finite input values, population totals, matrix dimensions, transition endpoints, and an arithmetic-only expression language; these checks do not establish scientific validity. The JSON Schema is available for editors and external tooling. Reproducible analysis workflows provide seeded first- and -total-order Sobol indices and bounded multi-start calibration with input hashes and -diagnostics. Built-in SIR, SEIR, SIRS, and SIS templates and complete worked examples +total-order Sobol indices [@Sobol2001] and bounded multi-start calibration with input +hashes and diagnostics. Built-in SIR, SEIR, SIRS, and SIS templates and complete worked examples are included in the documentation. This bounded modularity is configuration- and API-based; adding a numerical solver still requires Python development. PatchSim is released under GPL-3.0. +# Research impact statement + +PatchSim is in current research use at ARTPARK for foot-and-mouth disease +vaccination-scenario analysis across Karnataka districts, where it replaced a +project-specific implementation. The workflow models cattle and buffalo populations +stratified by age group and species. That analysis is unpublished at the time of +writing, and no publication enabled by the package has yet appeared. Published spatial +analysis of foot-and-mouth disease in India includes a state-level Bayesian space-time +model of reported outbreaks, which estimated a roughly 50% lower outbreak risk in states +covered by the vaccination programme [@Gunasekera2022]. The Karnataka analysis applies +a mechanistic patch model to the between-district allocation question. + +Near-term significance rests on what a third party can install, run, and check. The +package has been developed in public since April 2025, +with two tagged releases on PyPI and an archived release record [@patchsim]. Continuous +integration runs the automated test suite, linting, and a documentation build on every +pull request and push to the main branch. The tests cover configuration validation, the +expression +evaluator, both solvers, group stratification, the sensitivity and calibration +workflows, and the command-line interface. The seeded sensitivity and calibration +outputs described above carry input +hashes and diagnostics, so a third party can re-run and check a study. The documentation +on Read the Docs includes worked examples. + # AI usage disclosure GitHub Copilot, OpenAI Codex CLI (GPT-5), and Anthropic Claude Code assisted with code, -tests, documentation, and copy-editing. CodeRabbit assisted with code review. Model +tests, and documentation, and with language checks and paraphrasing of the authors' +draft of this paper. CodeRabbit assisted with code review. Model versions were not consistently retained for historical work. The authors reviewed, edited, tested, and validated all assisted outputs and made the scientific and architectural decisions.