1.1 Related work

Among the computational approaches made available to the public we find software tools that facilitate exploring and/or running epidemic models via graphical user interfaces (GUI), applications programming interfaces (API), or Web applications [5–8]. These include open-source simulators, written in Python, Julia, R, C++, and other programming languages, offering complete, often adaptable, implementations of different classes of epidemic models [9–24] and software libraries (e.g., Python or R packages) that act as building blocks for abstract and personalized implementations [8,13,19,25–30]. In terms of the analytical framework at the basis of these projects, we find compartmental [6,11], metapopulation [5], agent-based [8,10,12,13,16,17,19,24,24,25], and network-based [9,15,18,20,21,28,29] models. We also find projects offering a range of different models under the same umbrella [7,14,23,26,27,30]. While some tools target a specific disease such as COVID-19 [6,8,11,16,24], HIV [20], or influenza [12], others focus on classes of infectious diseases linked to specific types of transmission dynamics [5,9,10,13–15,19,25,27,29,30]. There is also heterogeneity in terms of the spatial scale of the analysis that these tools allow: from close contacts within a given area [7,9,15,18,21,22,28–30] to city [16,19,24], country [6,11,12] and global scales [5]. Furthermore, some projects are flexible and allow, within given constraints, the user to set the target scale of geographical analysis as input [8,10,12–14,17,19,20,23,25–27]. For this reason, before moving forward, we briefly situate Epydemix within the landscape of epidemic-modeling software.

Compartmental platforms range from the COVID-focused COVID-19 Scenarios [6] (interactive exploration without native calibration) and SimCOVID [11] (Simulink/MATLAB with calibration) to metapopulation tools such as GLEAMviz [5] (global mobility–aware GUI). In general, these tools emphasize scenario analysis over end-to-end inference such as the one offered in Epydemix.

Another group of tools is defined by agent-based modeling (ABM) approaches. Among those we find COVASIM [8] (Python, intra-host features, user-driven fitting), Agents.jl [10] (Julia, grid/graph/OSM with parameter search), Sampy [25] (Python, modular ABM for stochastic epidemic simulations with spatial structure and intervention modeling), the influenza models FluTE [12] and FRED [13] (both working on synthetic US populations), urban SARS-CoV-2 tools such as COMOKIT [16] and OpenABM-Covid19 [24], and behavior-centric frameworks like BESSIE [17] and Pyfectious [19] (the latter with Reinforcement Learning for policy optimization). For this class of models calibration is generally not supported and externalized to other packages.

Network-based tools includes CSonNet, VTES (didactic), GEMFsim (multi-language, multilayer), SimpactCyan (dynamic networks for HIV), Epinet (supporting ERGM inference), EoN (Python package designed for studying disease spread in static networks), and fast temporal-network SIR implementations [9,15,18,20,21,28,29]. While these tools provides a wide range of options to include network topology in the modeling they generally do not offer extensive inference or calibration features.

Finally, we find tools that allow the implementation of a range of model types such as EpiFire, MEmilio, Eir, Epilearn (with ML/statistical forecasting), and EpiModel (including deterministic compartmental models, stochastic individual contact models, and stochastic network models) [7,14,23,27,30], that prioritize breadth and the implementation of various models rather than their calibration to real data. In the S1 Text we provide a table with the main characteristics of all software tools reviewed here.

In this context, Epydemix deliberately centers on structured compartmental models, offering native, end-to-end calibration capabilities that are uncommon across existing platforms. It offers a flexible, and modular architecture for rapid model specification, simulation, parameter estimation, and scenario analysis geared to real-time epidemic assessment, policy-oriented planning, and short-term forecasting, especially when data are sparse, noisy, or insufficient to parameterize large-scale ABMs [31,32]. Epydemix is also designed to lower technical barriers by adopting Approximate Bayesian Computation (ABC), a likelihood-free inference framework that enables parameter estimation based solely on model simulations and observed data. This approach has gained traction in the epidemic modeling community in recent years [2,3,33]. Among other inference methods, ABC provides a conceptually transparent and general framework that directly links simulations to data through summary statistics, without requiring explicit likelihood evaluation. It is particularly suitable for stochastic or individual-based epidemic models, where the probabilistic nature of transmission and observation processes makes likelihood derivation impractical. Furthermore this calibration is general enough to support metapopulation or network models, while preserving reproducibility, interpretability, and a clear separation between model structure, data, and inference process.

2.1 Model definition and stochastic simulations

Epydemix supports the construction of general single-population stochastic compartmental models [37], in which individuals are grouped into compartments according to their epidemiological status (e.g., susceptible, infectious, recovered). Beyond the health status, compartments can also represent other relevant characteristics, such as vaccination status or behavioral attributes associated with the adoption or relaxation of NPIs. The progression of individuals through the different model compartments is represented by stochastic transitions between compartments. These transitions can be broadly classified into two categories: spontaneous transitions, which occur independently of interactions with other individuals (e.g., recovery or waning of immunity), and mediated transitions, which are driven by interactions between individuals in different compartments (e.g., infection due to contact between susceptible and infectious individuals).

For example, in the classic Susceptible-Infected-Recovered (SIR) model [37], susceptible individuals, in compartment S, are susceptible to the infection. By contacting infectious individuals, susceptibles may then transition to the infectious stage, and join compartment I. The infection process can be described using a notation borrowed from mass action reaction systems: , where β is the transmissibility of the pathogen. After the typical infectious period, infectious individuals spontaneously transition to the recovered compartment R. These transition can be described as , where μ is the recovery rate. The infection process is a classic example of a mediated transition. The recovery process instead is an example of a spontaneous transition. The package provides full flexibility in defining both the number and type of compartments, enabling the development of advanced models beyond classic SIR-like structures. As mentioned above, this includes, for example, compartments for vaccinated individuals and behavioral dynamics. Individuals can be further categorized into demographic groups, such as age brackets (see Sect 2.2 for more details). Accordingly, we denote the number of individuals in compartment X (e.g., ) and demographic group k as X_k. Moreover, we define X_total as the sum of individuals in compartment X across all demographic groups (i.e., ). It follows that, for example, S_k indicates the number of susceptible individuals in demographic group k, and S_total the total number of susceptible individuals across all groups.

Models are built using the EpiModel class which requires: 1) the compartments, defining the possible states of individuals, 2) the transitions among them, and 3) the parameters governing such transitions. Canonical models such as the Susceptible-Infectious-Recovered (SIR), Susceptible-Exposed-Infectious-Recovered (SEIR), and Susceptible-Infectious-Susceptible (SIS) are provided as predefined templates.

Simulations in Epydemix are stochastic and follow a chain binomial approach to model transitions between compartments. At each time step, the number of individuals transitioning from compartment X_k to Y_k is drawn from a binomial distribution, , where X_k denotes the number of individuals currently in the source compartment, and represents the probability of transition within the interval . By default, transition probabilities are computed by converting transition rates (i.e., ) into discrete-time risks using the standard exponential transformation:

When a compartment has multiple possible destination states, transitions are modeled using a multinomial extension of the chain binomial process (see S1 Text).

By default, two types of transitions are supported: spontaneous and mediated transitions. For spontaneous transitions, the rate is directly defined by the user-specified parameter. In the case of mediated transitions, the rate additionally incorporates an interaction term form that depends on the size of the mediating compartment (e.g., the number of infectious individuals in transmission processes). For illustrative purposes, let us consider a classic SIR model. In this case, the rate of recovery will be , where is the inverse of the infectious period. In the simplest case, for all k. The rate of infection for group k will be instead , where β is the transmission rate, C is the contact matrix (see Sect 2.2 for more details), and is the total number of individuals in group . We refer the reader to the S1 Text for a more detailed mathematical formulation of the SIR model.

Single stochastic realizations of the model are generated using the simulate function, which returns a Trajectory object containing the compartment dynamics (e.g., X_k(t)), the transition counts (e.g., ), and the parameters used in the simulations (e.g., the transition rates). The run_simulations method performs multiple realizations, returning a SimulationResults object with all trajectories and summary statistics like medians and confidence intervals. In Sect 3.1.1 of the Results, we provide a practical example illustrating model definition and simulation.

2.2 Integration of real-world population demographic and contact patterns data

By default, the EpiModel class is initialized with a population of 100,000 individuals in a single demographic group, equivalent to a homogeneous mixing assumption [37]. However, the Population class can be used to define the essential information about the population, including the total number of individuals, their distribution across demographic groups, and the contact rates between groups. This information serves as input for the simulations, determining the initial conditions and the structure of interactions that drive the transmission dynamics. In particular, the demographic composition informs how individuals are allocated at initialization, while contact matrices are typically used to modulate the infection rate between groups during the stochastic simulation process. Population objects can also be instantiated using real-world demographic data, allowing users to ground their simulations in realistic settings. Indeed, the package is complemented by an external online repository (Epydemix Data), which provides access to population structures and synthetic age-stratified contact matrices for over 400 regions worldwide. The data is hosted in a dedicated GitHub repository [38], and include age-stratified population distributions along with contact matrices that characterize interactions across different settings, including households, workplaces, schools, and community environments. The contact matrices are provided in three distinct variants derived from the synthetic datasets developed by Mistry et al., 2021 [39], Prem et al., 2021 [40], and Prem et al., 2017 [41]. The dataset covers the majority of countries worldwide, with sub-national demographic information available for selected regions. The majority of population data comes from the United Nations World Population Prospects [42]. A full list of supported regions, datasets, and sources is available on GitHub [38].

Users can easily import data using the load_epydemix_population function, which creates a Population object for the desired location. Alternatively, users can define custom populations by providing their own dataset as input. The resulting Population object can be set for simulations with the set_population method of EpiModel. Additional functionalities simplify population customization and exploration. For example, users can define custom age groups and pass them to load_epydemix_population to achieve the desired granularity.

2.3 Advanced modeling features

The previous subsections introduced the components required to define and simulate epidemic models. Building on this foundation, the package also supports a range of advanced features that extend its modeling capabilities.

2.4 Model calibration

Epydemix supports the full pipeline of epidemic modeling, including parameter inference through simulation-based calibration. Epydemix adopts an Approximate Bayesian Computation approach, which is particularly well suited for stochastic simulation settings, as it enables inference by comparing observed and simulated data without requiring explicit likelihood evaluation [3,4]. The core object for models’ calibration is the ABCSampler, which requires the following key inputs: i) prior distributions for free model parameters , ii) a distance function , iii) a simulation function, and iv) the observed data . Prior distributions represent initial beliefs about parameter values and must be specified using scipy.stats distribution functions, which offer a wide range of options for both continuous and discrete parameters. For instance, to reflect minimal prior knowledge, one may adopt flat or broad priors, such as a uniform distribution defined over a plausible range or a wide normal distribution centered around an initial guess. The distance function quantifies the discrepancy between simulated and observed data, guiding parameters’ selection. For example, one may use the Euclidean distance between simulated and observed incidence time series, or compute the (absolute) differences on key summary statistics such as peak incidence or epidemic duration. The simulation function is used by the calibration algorithm to generate a model output and must conform to minimal interface requirements. At its simplest, this function acts as a wrapper around the Epydemix simulate function which runs a single stochastic realization for a given model, specifying the output used for distance calculations and parameters’ selection. If needed, users can extend the wrapper to include more complex input pre-processing (e.g., custom model initialization) or output transformations (e.g., aggregating compartments or computing summary statistics before distance calculation). This design allows calibration not only of models built with Epydemix but also of external models. As long as the simulation function adheres to the minimal required output structure, models developed outside the package can be used within an ABCSampler object. Finally, the observed data represent the empirical measurements (e.g., observed incidence time series) against which model outputs are compared and are required for the calculation of distances during the calibration process.

The package supports three ABC algorithms for parameter inference [2,3]. They can be executed using the calibrate method of an ABCSampler object, specifying the desired strategy.

The basic ABC rejection algorithm is performed by setting strategy = "rejection" when calling the calibrate method of ABCSampler. It requires defining a tolerance ε and a population size P. The algorithm iteratively samples the parameters from the prior distributions and executes the simulation function to produce an output which is compared to observed data using . Parameters are accepted if . This process continues until P parameter sets are accepted, approximating the posterior distribution of free parameters. This approach is simple and intuitive, but has limitations, such as determining an appropriate tolerance ε. Smaller values improve accuracy but slow down the calibration, while larger values speed up convergence at the cost of precision. Additionally, the prior distribution remains fixed, ignoring the insights gained during the process.

To address these issues, the package offers an alternative algorithm that can be used by setting strategy = "top_fraction". This replaces the fixed tolerance with a total simulation budget B (i.e., total number of simulations) and a selection percentage x. Sampling, simulations, and comparison with data continue until the budget is exhausted, after which the top of parameter sets are selected based on the distance metric. Hence, , where is the α-th percentile. This approach is equivalent to set a tolerance implicitly defined by the largest distance for top simulations given the simulation budget.

A more advanced algorithm is an ABC method based on Sequential Monte Carlo (ABC-SMC) that extends the rejection approach by using T generations with progressively smaller tolerances. This calibration method is available by setting strategy = "smc". The implementation of the ABC-SMC methodology follows Ref [4]. In brief, each generation’s prior distribution is the posterior from the previous generation, perturbed by a kernel function. This iterative process starts with a broad prior and high tolerance, refining the parameter space with each generation. The final generation yields a refined approximation of the posterior distribution. In the package, by default, the first generation begins with an infinite tolerance, and subsequent values are computed as the median (or another user-specified quantile) of distances from accepted particles in the previous generation [46,47]. Alternatively, a specific tolerance schedule can be provided. A component-wise Gaussian kernel is used for continuous parameters, while discrete parameters employ a discrete jump kernel [48]. Users have the flexibility to define their own perturbation kernels via the Perturbation class.

The ABC-SMC algorithm offers the highest accuracy, but can be more computationally demanding. The simple rejection algorithm is a quick and easy option for exploring models or prior distributions. The modified rejection approach ensures results within a fixed time frame, but is generally less accurate. It is particularly useful for exploratory tasks or recurrent processes with strict runtime constraints. For all algorithms, stopping conditions such as maximum runtime, simulation budget, or minimum tolerance (ABC-SMC only) can be defined by the user. The pseudocode for the three calibration algorithms is provided in the S1 Text. For all the three algorithms, the calibrate method returns a CalibrationResults object, providing access to estimated posterior distributions for free parameters, selected trajectories, and general information about the parameters used in the calibration algorithm. After the calibration step is completed, the run_projections method of ABCSampler allows running projections by sampling from the approximated posterior distribution. See Sect 3.1.2 of the Results for a practical example illustrating the model calibration process.

2.5 Visualization

The package provides several options to visualize models’ features and outputs. Population distributions across demographic groups and contact matrices can be visualized using the plot_population and plot_contact_matrix functions. The plot_spectral_radius function plots the spectral radius of the contact matrix over time. This quantity is proportional to the model’s reproduction number [49]. Variations to the spectral radius induced by mitigation policies can be used to quantify the potential impact of interventions on epidemic dynamics. Simulation outputs, such as the median and confidence intervals of the number of individuals across each compartment as well as outputs from the calibration algorithms can also be explored with built-in visualizations. The plot_quantiles function displays summary statistics of simulated trajectories, while plot_posterior_distribution_2d, plot_posterior_distribution, and plot_distance_distribution visualize the joint posterior distribution of two parameters, the marginal posterior distribution of a single parameter, and the distribution of distances for accepted parameters, respectively.

3.1 Example usages

3.1.1 Model definition and simulation.

We begin by providing an example of how to use the package to define and simulate epidemic models. We consider a simple SIR model, which can be created with the following code:

The first block initializes the model by specifying the compartments and parameters. Both can also be added after initialization using the add_compartments and add_parameter methods, respectively. Parameters can also be passed directly to transitions as values. The next two blocks define the model’s transitions. In both cases, we specify the source and target compartments, the parameters for the transition, and the transition type. For the recovery process (a spontaneous transition), only the transition rate is required, whereas for the infection process, the name of the compartment mediating the transition must also be provided. The final block imports population data for Italy and assigns it to the model. After these initializations, we can run a given number of stochastic simulations over a defined time window and visualize some outputs by using the following set of instructions:

We note how the parameter Nsim can be used to set the number of simulations. Unless specified, its default value is set to 100. The output of the code can be seen in Fig 2A, which shows the median and 90% confidence intervals of the number of individuals in compartments S, I, and R summing them across all age-groups, i.e., X_total with .

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 2. A) Time series showing the simulated number of susceptible, infected, and recovered individuals across all age-groups (median and 90% confidence intervals).

B) Time series showing the total number of infected individuals (median and 90% confidence intervals) with and without interventions, highlighting the impact of NPIs in flattening the epidemic curve. C) Percentage change in the spectral radius of the overall contact matrix during workplace and school closures, illustrating the reduction in contact dynamics. D) Boxplots summarizing the impact of interventions, including the percentage of averted infections and the reduction in peak size.

https://doi.org/10.1371/journal.pcbi.1013735.g002

Next, we incorporate public health interventions to simulate a scenario in which modelers aim to quantify the potential effects of NPIs on an outbreak. The first intervention is a partial school closure, reducing contacts in the school layer to 35% of the original value (i.e., a 65% reduction). This can be added to the model as follows:

The second intervention is a partial workplace closure, reducing contacts in the workplace layer by 70%, which can be done similarly (code not shown). Additionally, we consider a range of other measures, such as mandatory masking and general social distancing policies, which reduce the transmission parameter (β) over a specified period from 0.045 (the initial value) to 0.02. This measure can be introduced in the model with the following code:

We finally re-run the model with these interventions and compare the results. Fig 2B shows the output of the plot_quantiles function providing the evolution of the total number of infected individuals over time for the SIR model we defined above, and the analogous model without interventions, highlighting the flattening of the epidemic curve due to interventions. Fig 2C visualizes the impact of interventions on contact patterns, plotting the percentage reduction in the spectral radius of the overall contact matrix over time. As mentioned, the spectral radius is the largest eigenvalue of the contact matrix and is proportional to the basic reproduction number [49]. Finally, Fig 2D demonstrates the effects of interventions in terms of total averted infections and the percentage reduction in peak intensity, computed with minimal additional manipulation of the SimulationResults outputs.

3.1.2 Model calibration.

In this second example, we demonstrate how Epydemix can be used to calibrate epidemic models to observed data using ABC techniques. As target data we use synthetically generated daily new infection counts (i.e., daily incidence) from an SIR model applied to a population representative of Indonesia. The synthetic data is obtained by fixing the transition rates to specific values and adding noise to the resulting daily incidence to mimic the variability typical of real data. In particular, we set the transmissibility to 0.02 and the recovery rate to . At each time step, we add random noise of up to to the simulated daily incidence, ensuring that no negative values occur by setting any of such cases to zero.

Following a similar procedure to the one described above, we define a new SIR model which will fit to the synthetic data. In particular, our objective is to estimate the posterior distribution of both the transmission and recovery rates based on the observed data. As a first step, we need to define the simulation function to ensure that the calibration algorithm correctly processes the model’s output. This can be achieved as follows:

The simulation function serves as a wrapper around the simulate function, simply passing the arguments to it and returning a dictionary containing a key named "data". This key stores the output quantity from the model which will be compared to the observed data using the distance function. It is important to emphasize that the simulation function must always return a dictionary containing the key "data". The value associated with this key will then be passed to the distance function for the selection of stochastic trajectories during the calibration process.

As the second step, we define the prior distributions for the free parameters using the scipy.stats distribution functions:

In both cases, we assume a uniform prior, with the transmissibility and the recovery rate . It is important to note that in scipy.stats.uniform, the second argument does not specify the upper bound of the uniform range but rather the range’s width.

Next, we define the ABCSampler object, which takes as inputs the simulation function, prior distributions, other parameters, the observed data, and the error metric (root mean squared error in this example):

We are now ready to run the calibration. To do so, we simply call the calibrate method of the ABCSampler object, specifying the calibration strategy and its specific arguments.

In this example, we opted to run all three calibration algorithms. In particular, we use the "rejection" approach with 1,000 particles accepted and a tolerance of 550,000, the "top_fraction" approach with 10,000 total simulation budget and top 10% selected, and finally the "smc" approach with 5 generations and 1,000 particles accepted in each generation.

Fig 3A compares the calibration results, plotting the observed data (black dots) alongside the median and 90% confidence intervals of the simulated new infections for each strategy. All three methods produce a good fit to the observed data, with slight differences in the confidence interval widths, reflecting variations in uncertainty across strategies. Fig 3B shows the joint posterior distributions of the transmission and recovery rates for each strategy, with the true parameters (red cross) used to generate the data. While all strategies converge on similar parameter regions, the density and shape of the posterior distributions differ, with the ABC-SMC resulting in the less disperse posterior. The similarity between ABC-SMC and ABC Rejection results is expected, as the tolerance used in ABC rejection matches the final generation’s tolerance in ABC-SMC.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 3. A) Calibration results showing the fit of simulated new infections (medians and 90% confidence intervals) to synthetic data (black dots) for each calibration strategy.

B) Joint posterior distributions of the transmissibility and recovery rate for each strategy. The parameters used to generate the data are denoted with a red cross.

https://doi.org/10.1371/journal.pcbi.1013735.g003

3.2 Modeling COVID-19 in Massachusetts

As detailed case study we develop a realistic epidemic model to reproduce the spread of SARS-CoV-2 in early 2020 in Massachusetts, USA. The model accounts for contact reductions due to social distancing recommendations and lockdowns, seasonal variation in transmissibility, and disease-related mortality. We calibrate the model’s free parameters using real weekly reported deaths, between 2020/02/23 and 2020/06/01. The model accounts for 10 age groups (i.e., 0–9, 10–19, 20–24, 25–29, 30–39, , 80 + ) and incorporates population and contact matrices representative of the location under investigation. The compartmental structure of the model is illustrated in Fig 4A. Briefly, the model follows a SEIR-like structure with additional compartments to account for disease-related mortality. Specifically, multiple death-related compartments are included to represent the delay Δ of a few days between the end of the infectious period (i.e., exiting the I compartment) and death (i.e., the final transition to D₄). This implementation allows considering Erlang distributions of delays [50]. In particular, we considered four intermediate transitions steps. The transmissibility β is modulated by a seasonal factor s(t), assumed to follow a sinusoidal pattern with an annual period, peaking in mid-January in the Northern hemisphere. The amplitude of this seasonal variation is treated as a free parameter. Additionally, the model incorporates a time-dependent modulation of contact rates, r(t), estimated using mobility data from the COVID-19 Community Mobility Report published by Google [51]. Full details of the model, including the system of equations, are provided in the S1 Text. The code required to reproduce this analysis is more involved than the previous ones; therefore, we do not include snippets here. However, a full tutorial on this case study is available online on the package repository [35].

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 4. A) Schematic representation of the extended SEIR model, incorporating additional compartments to account for disease-related mortality.

B) Projected weekly COVID-19 deaths in Massachusetts under different reopening scenarios. The black dots represent observed data, while the shaded areas indicate uncertainty intervals for the calibrated model (green) as well as different reopening strategies: status quo (orange), moderate (purple), and strong (pink).

https://doi.org/10.1371/journal.pcbi.1013735.g004

We calibrate the model using the ABC-SMC algorithm, with 10 generations and 1,000 particles per generation. Free model’s parameters include the basic reproduction number R₀, the initial number of infected I₀, the amplitude of seasonal variation in transmissibility, and the delay Δ between the end of the infectious period and the time when deaths are reported. As detailed in the S1 Text, for all parameters we choose uniform flat prior distributions. In Fig 4B, we present the reported weekly COVID-19 deaths in Massachusetts alongside the median and 90% confidence intervals of simulated weekly deaths projected by the calibrated model. The projections closely align with the reported data, with a weighted median absolute percentage error of 18%. In the S1 Text we show the posterior distributions of free parameters. For R₀, the calibration yields a median of 2.18 with a 90% credible interval of [2.03,2.39].

After the calibration step, we perform out-of-sample scenario projections up to 2020/08/02, considering three different scenarios: (i) no relaxation of NPIs, where intervention levels remain unchanged from the last observed value in the calibration window, (ii) moderate relaxation, with contact rates increasing by 30%, and (iii) strong relaxation, with a 50% increase in contact rates, approaching pre-pandemic levels. Additional details on the NPIs assumptions are provided in the S1 Text. In the first scenario, the downward trend in cases continues, aligning with the reported data. In the second, the trend reverses in mid-July, leading to a mild resurgence over the summer. In contrast, strong relaxation would have caused a significant resurgence in deaths during summer 2020.