epymorph: Spatially-explicit modeling of infectious disease as a Python library

The epymorph package is the product of the EpiMoRPH (Epidemiological Modeling Resources for Public Health) project, and aims to provide a simplified framework for completing the full lifecycle of a spatial modeling experiment. epymorph streamlines methods for building, simulating, and fitting, metapopulation models of infectious pathogens. This Python package is easily accessible to beginning modelers, while also sophisticated enough to allow rapid design and execution of complex modeling experiments by highly experienced modelers. Specific aims include dramatic streamlining of model building speed, increased model transparency, automated fitting of models to observed data, and easy transportability of models across temporal and geographic scenarios.

See the About page for more information about the motivations behind EpiMoRPH.

Core Features: Build and explore spatial models fast!

Pre-built catalogs of automated spatial disease models with mix-and-match components

epymorph is designed to standardize and (semi)-automate the workflow for creating, simulating, vizualizing, and fitting spatial epidemiological models, with an emphasis on abstraction and modularity. In epymorph, users can select and augment pre-built intra-population models (IPMs; compartmental disease models, based on ordinary differential equations); similarly, they can leverage pre-built movement models (MM’s; temporal and spatial patterns of movement); and they can deploy these models in real or abstract locations. epymorph does the heavy lifting in collecting all the data required to run simulations in specific locations. The key feature of epymorph is that our pre-built library of IPMs and MMs are cross-compatible, so that users can quickly mix and match movement styles with different compartmental models to suit their specific needs or to test certain hypotheses (e.g., how different movement styles affect local and regional patterns of disease).

A powerful GEO subsystem to streamline access to location-specific data of many sorts down to the Census Block Group level in any area of the USA

A streamlined GEO Scope specification system allows users to identify any set of US Census-delineated locations to use as nodes in the simulation, from State to County to Census Tract to Census Block Group. Accessing and munging the data to drive a model – ranging from population sizes at each node, to numbers of commuters between nodes, to time-varying meteorological data for each node – constitutes a main time bottleneck for modelers. epymorph does the hard work for you, with semi-automated tools to help you quickly extract the data your model needs. epymorph provides a growing set of web-accessible datasets including US Census data (e.g., ACS5), movement databases (e.g., LODES8), and meteorological data from PRISM. You simply provide epymorph the Scope and timeframe, and epymorph queries the relevant data sources, extracts, and munges the specified data to match your modeling experiment. Data currently made accessible include local demographic characteristics, including distribution of age classes, commuter data, temperature, precipitation, relative humidity.

Built-in time-series and geo-spatial plotting functions

We have created a number of useful visualize tools for epymorph output, without needing to become expert in manipulating graphing and visualization packages. These include time-series line plots (e.g., infections over time per model node), and static maps (e.g., choropleth maps plotting summary statistics per GEO node).

Features for Advanced Modelers

Built-in parameter estimation with particle filtering, supported by real surveillance data sets

Advanced users with experience in model-fitting can leverage our built-in model fitting engine to fit epymorph models to real or simulated surveillance data. This is a major advancement for modelers, who can now quickly test the quality of hindcasts produced from different IPMs and MMs fit to real data sets, enabling advanced hypothesis testing and the design of forecasting pipelines. The epymorph model-fitting engine provides flexible and powerful particle filtering algorithms for both time-varying and static parameter estimation. Parameters can be estimated per node in the GEO Scope, using built-in localization techniques, which provides a high-quality understanding of spatial heterogeneities in transmission and disease processes. Our GEO subsystem can fetch real surveillance data (e.g., hospitalization or mortality counts) for influenza, SARS-CoV-2, and RSV. Or, users can provide custom data surveillance data sets (e.g., simulated or unrealeased).

Rapidly create and customize advanced intrapopulation models

Our system of defining compartmental disease models (IPMs) is flexible and powerful. Users can alter epymorph’s pre-built IPMs, using a straightforward and familiar syntax. Users can also use our multi-strata modeling functions to easily create sophisticated composite models with sub-strata based on age-classes, risk-classes, or host species (e.g., vector-borne or zoonotic diseases). A separate IPM can be selected (or built) for each strata, then combined into a composite model by linking influences or compartments between strata. A separate movement model (MM) can be selected (or built) and connected to each strata, e.g., to model different movement dynamics per age-class, or different movement dynamics per species in a multi-species model.

Flexibly define customized movement models

Users can combine and modify our pre-built movement models, or they can create their own movement models that leverage user-provided data sets in the GEO objects (see above). Our carefully developed MM specification syntax allows movement models to capture an enormous variety of potential movement patterns including migration, commuter movements, and custom-triggered movement. Overlapping movement dynamics can be easily modeled, e.g., weekday versus weekend movement, or commuter movement that happens multiple times per day, seasonal migrations, or movements on particular holidays. Users can also define functions that create custom movement matrices, for instance through customized gravity kernel functions that leverage data from each node in the GEO Scope.

Specifying custom geographies

While our pre-built library of models are cross-compatible, it may be the case that users want to simulate our IPMs and MMs in geographies that do not nicely fit into US Census-delineated areas. For instance, perhaps they want to use zip codes, or they want to specify GEO boundaries for animal diseases that don’t fit nicely into government jurisdictions. Users can leverage epymorph’s powerful GEO subsystem to specify custom Geo Scopes and still fetch data from a variety of common data sources at their custom spatial locations. Or, users can use epymorph to import their own datasets from CSV files; epymorph will help to ensure the imported data is formatted and shaped correctly to match the selected modeling granularity, geography, and node structure.