Basic Setup

Previous: Getting Started. Next: Working with Models. Also, see SimBA

ramp.xds is based on a mathematical framework for model building that is modular, flexible and extensible. Using the built-in functions, it’s comparatively easy to build highly realistic models by starting simple and adding features one at a time. We call this progressive model building.

In the vignette Getting Started, we introduced the function xds_setup(). From a software design perspective, a setup interface can’t possibly anticipate the needs of every end user without constraining possibilities. The point of xds_setup() is to help build models up to a certain level of complexity. Instead, we have adopted a system for progressive model building based on a mathematical framework and the idea of scaling complexity.

Progressive model building is a practical method for building complex models in two phases:

Basic Setup is handled by the function xds_setup(). It’s designed to help a user get started with a properly formulated interface that can handle spatial dynamics, structured aquatic habitats, and a stratified human population.
Advanced Setup handles advanced features, including exogenous forcing, vector control, and other modes of malaria control, human demography and aging, and host population stratification.

In the following, we introduce Basic Setup

Modularity and Etensibility

A mathematical framework supported the design of ramp.xds. That framework handles a subset of the universe of all possible models. That subset can be understood as nested, hierarchical sets of models expanding out from a set of simple base models. Notably, the math works bass ackwards. We could be more rigorous in defining what we mean by all that, but this vignette is not the place for it. We use the concept to motivate progressive model building.

Basic setup was designed around simple models with structural flexibility. Each model returned by basic setup could serve as a platform for developing models of unbounded realism and complexity. To make this work, the software built in ports and junctions that could handle a large set of advanced features, but most of these features would be turned off for basic setup.

Modularity

The framework is designed around five dynamical components organized into three chunks:

Human / vertebrate host ecology, infection and immunity, called the XH-component
- human (or host) demography (H-component) including births, deaths, aging and migration;
- malaria epidemiology (X-component), in the narrow sense; or more generally, the dynamics of infection and immunity in the host population;
Adult mosquito ecology and infection dynamics, called the MYZ-component
- mosquito ecology: the M-component
- mosquito infection dynamics: the Y-component
- parasite development: the Z-component
Aquatic mosquito ecology, called the L-component

These three chunks are connected by two interfaces. The first two chunks are connected through the rigid interface describing blood feeding and transmission. The last two chunks are connected through egg laying and emergence.

Figure 2 Modular dynamic components that form the core of ramp.xds

In general, module is the term we use to describe an element in the model library. Since the parameter values can be changed, each module defines a model family in the form of a system of differential or difference equations. Each family is defined by a set of states and state transitions (i.e. by the topology of the graph) for a single population (nStrata=1).

For example, the SIS module for the X-component is the SIS compartmental model family for human infections. It’s called a model family because each unique set of parameters would define a different model.

In its simplest form, each model family represents the state of a single population, but any model can replicate those states and sub-divide a single population into sub-populations with different parameters. These are population strata for the X-component; adult mosquitoes are found in patches for the MYZ-component; immature mosquitoes in aquatic habitats for L-component. In ramp.xds it is comparatively simple to configure a model with multiple strata, patches, and habitats.

For our purposes, Basic Setup encompasses the configurable options in xds_setup(). Each model returned by xds_setup is characterized by:

A model family for each dynamical component, including model parameters. The model object also stores initial values.
The model structure, including the number of patches, the number of habitats and their membership in the patches, and the number of human population strata and their residency within the strata.
Functions that define exogenous variables and functional responses that drive exogenous forcing by weather and malaria control.

The software supports a modular framework for model building that is highly flexible and extensible. It’s capable of building very realistic models, but progressive setup embraces a model-building philosophy of starting simple and adding realism or complexity one step at a time.

The demo in Getting Started sets up one version of the Ross-Macdonald model. It illustrates how the software has streamlined the process of building fairly simple models. The following sections describe how to make ramp.xds build models that are much more complicated and realistic.

As described in Getting Started, the xds_setup() function ramp.xds has assigned default options for everything. Each model must configure three dynamical components: human epidemiology; adult mosquito ecology and infection dynamics; and aquatic mosquito ecology. Each one of these three dynamical component is configured by specifying a model name (as a string) and options, passed as a named list, to override the defaults for the model:

Xname dispatches a module for the X component. The setup default model is Xname="SIS" and default parameters for the SIS model are defined in create_Xpar_SIS. To replace the default values at setup, a named list can be passed as Xopts = list(...) and the named values in Xopts will be he values of named parameters and the initial values of named variables instead of the defaults. (The human demographic module for the H-component is set up as an advanced option.)
MYZname dispatches a module for the MYZ component. The setup default model is MYZname="macdonald" and default parameters for the macdonald model are defined in make_MYZpar_macdonald. To replace the default values at setup, a named list can be passed as MYZopts = list(...) and the named values in MYZopts will set the values of named parameters and the initial values of named variables instead of the defaults.
Lname dispatches a module for the L component. The setup default model is the trivial model Lname = "trivial". It has no variables, but it passes the outputs – emerging adults – as a parameter. To replace the default values at setup, a named list can be passed as Lopts = list(...) and the values in Lopts will set the values of named parameters and the initial values of named variables instead of the defaults.

Defaults

library(ramp.xds)

Thu function call:

model1 = xds_setup()

returns the same values as the function call:

model2 = xds_setup(Xname = "SIS", 
                   MYZname = "macdonald", 
                   Lname = "trivial")

Structural Parameters

Structural parameters describe things like the number of patches, the number of population strata, the number of aquatic habitats, the number of host species, and the number of vector species. xds_setup sets up models with one host species and one vector species, users can configure a malaria landscape with spatial dynamics, structured aquatic habitats, and multiple human / host population strata. Basic setup was developed to ensure that all interfaces are set up properly when there are multiple patches, multiple habitats, multiple population strata, and malaria importation. The software and documentation follow the mathematical framework formulas and (with small changes) the notation in Wu SL, et. al. 2023. The following structural parameters can be set through xds_setup:

nPatches or $n_p$ is the number of patches in the model.
membership is set up by passing a vector with the identity of patch where each habitat can be found, and it sets up the habitat membership matrix, $Q$ . Setup sets the value of a variable describing the number of habitats, $n_q$ = nHabitats <- length(membership). One configurable option is searchQ with the habitat search weights.
HPop is a vector with human population density, and residence is a vector describing the location of the patch where each stratum resides. Setup checks that length(HPop) == length(residence) and sets the number of strata, $n_h$ or nStrata <- length(residence). It is also possible to configure heterogeneous biting at the command line by passing searchH
If nPatches >1 then other setup-configurable options are to pass:
- a matrix $K$ or calK describing mosquito dispersal among the patches.
- a matrix $\Theta$ or TimeSpent can be passed to configure human time spent

To learn more, we suggest taking a look at the 5-3-4 Vignette, a model with 5 aquatic habitats, 3 patches, and 4 human population strata.

Spatial Mosquito Ecology

In ramp.xds, mosquito spatial ecology is implemented in a patch-based simulation model: a spatial domain is subdivided into patches; and each patch contains an arbitrary number of habitats.

Spatial Transmission Dynamics

In ramp.xds, malaria spatial dynamics are implemented through a model of blood feeding in a patch-based simulation model.

model5 <- xds_setup(nPatches=4)

Human / Host Population Strata

Advanced Setup

NOTE: As demos for these advanced options get developed, we will add the links here.

Advanced Setup Options: During basic setup, two advanced options can be configured, but most of the advanced options must be added after basic setup.

Spatial Dynamics

Spatial Heterogeneity –
Human Mobility –
Malaria Importation includes travel and visitors
- Travel Malaria –In basic setup, travel malaria is set up to model exposure while traveling, but time spent traveling and the travel FoI are set to zero.
- Visiting – In basic setup, visiting is set up but the availability of visitors is set to zero.
Exposure – Since catch counts data for mosquitoes are usually well-described by the negative binomial distribution family, ramp.xds has implemented a step between the computation of the EIR and the FoI to model environmental heterogeneity based on a probability distribution function describing the number of infective bites per person. By default, xds_setup configures a Poisson model, but this can be changed.
Human Demography – In basic setup, the human demographic model is the trivial model, but it can be configured to include
- Vital dynamics: births, deaths
- Migration
- Cohort dynamics and aging
- Pregnancy
Forcing – set up exogenous forcing, including exogenous variables (e.g. weather and hydrology) and the functional responses to compute mosquito bionomic parameters
Vector Control – set up vector control, including
Health Systems – a variety of functions to handle surveillance and malaria control through health systems, including care seeking, mass vaccination, IPTp
Multiple Vector Species – Each vector species has spatial structure, but it is also possible to configure other vector species (or type).
Multiple Host Species – Each host species can be stratified, but it is also possible to configure other host species (or types) to make setup and configuration easier.

Figure 3 – The modular structure and extensibility of ramp.xds.