Getting Started with ramp.xds

Source: vignettes/GettingStarted.Rmd

ramp.xds reduces the costs of building, solving, and analyzing models describing the epidemiology, transmission dynamics and control of malaria and other mosquito-transmitted pathogens. This vignette gives a demonstration and a basic introduction. Another useful vignette is a primer for working with the xds model object, called Working with Models in ramp.xds.

Installation

The software was developed in RStudio. To download the R package, run these commands:

library(devtools)
devtools::install_github("dd-harp/ramp.xds")

Then load ramp.xds:

Demo

With ramp.xds it’s easy to build models for the transmission dynamics and control of malaria or other mosquito-borne pathogens.

  • xds_setup() returns a fully configured model (with all the default settings, see below);
model <- xds_setup()
  • xds_solve() solves a model, parses the outputs, and computes most of the standard terms.
model <- xds_solve(model)

Note that model was passed to xds_solve, and the return value replaces model. Before xds_solve, model$outputs was an empty list. After solving, the outputs are stored as model$outputs:

names(model$outputs)
## [1] "time"   "last_y" "orbits" "terms"  "deout"

The outputs from solving a system of equations include:

  • time – are the time points when the values of the dependent variables were evaluated

  • last_y – is the final state

  • orbits – are the solutions with the variables parsed by name

  • terms – the dynamical terms describing transmission, including the EIR.

  • deout – the raw (unparsed) outputs

  • bionomics – For models with exogenous forcing, xds_solve stores the values of mosquito bionomic parameters

When xds_solve is called, the xds model object it returns has replaced any old values. To do anything with the outputs, the user will probably have to write a wrapper function that solves and extracts.

Functions like get_EIR() make it easy to examine or save a set of standard outputs without delving into the details.

head(get_EIR(model), 3)
##              [,1]
## [1,] 0.0002850000
## [2,] 0.0002622311
## [3,] 0.0002412851

ramp.xds includes functions to plot standard outputs:

par(mfrow = c(2,2))
xds_plot_X(model)
xds_plot_M(model)
xds_plot_Y(model, add=T)
xds_plot_Z(model, add=T)
xds_plot_PR(model)
xds_plot_EIR(model)
**Figure 1:** Plotting standard outputs

Figure 1: Plotting standard outputs

Trivial Models and Trace Functions

The software was designed to be fully modular. A basic requirement for full modularity is that every dynamical component must include a trace module. In each trace module, no variables are defined, but the dynamical terms needed by related dynamical components include a fully configurable trace function. In above example, the $\cal L$ component was trivial, but we can create a new model by modifying the old one. First, we define F_season and the mean values of Lambda

Lo = list(
       Lambda=500, 
       F_season = function(t){return(1+sin(2*pi*(t+90)/365))})
model_1 <- make_Lpar("trivial", model, 1, Lo)
model_1 <- last_to_inits(model_1)
model_1 <- xds_solve(model_1, Tmax=365*3) 
par(mfrow = c(1,2))
xds_plot_X(model_1)
xds_plot_M(model_1)
xds_plot_Y(model_1, add=T)
xds_plot_Z(model_1, add=T)
**Figure 2:** Outputs with Seasonal Forced Emergence using a Trace Function

Figure 2: Outputs with Seasonal Forced Emergence using a Trace Function

For more information, see the vignette Trace Functions

Model Building

From a design perspective, the setup interface can’t possibly anticipate the needs of every end user. Instead, it has adopted a system for setting up models based on the principle of scaling complexity: the framework regards a subset of the universe of possible models as a nested, hierarchical set. In some limiting case, some complex model are equivalent to a simpler model. Rather than try to build one big supermodel, the framework envisions the software around model families developed at varying levels of complexity.

In general, the term model family describes a single dynamical component defined by a set of states and transitions in the form of a system of differential or difference equations: one example 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. In practice, a single population is subdivided into sub-populations: human population strata or adult mosquitoes in patches or immature mosquitoes in aquatic habitats. In ramp.xds it is comparatively simple to configure a model with multiple strata, patches, and habitats.

Each model developed in ramp.xds is thus characterized by:

  • The choice of model family for each dynamical component and the model parameters.

  • 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 concept for designing a setup interface to support complexity scaling in model building works bass ackwards. The framework was designed around models that could be linked to serve as a platform that could explore models of unbounded realism and complexity, but it would need to start very simple. To work out all the kinks, the software would have to build 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. Model building is handled in two steps:

  • 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

  • Advanced Setup handles exogenous forcing, vector control, and other modes of malaria control, human demography and aging, and host population stratification.

Another set of functions has been developed to work with models. See the related vignette Working with Models. Also, see the related software package ramp.work.

Modularity

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

  1. The vertebrate host population, denoted $\cal XH$:

    • human (or host) demography ($\cal H$) including births, deaths, aging and migration;

    • malaria epidemiology ($\cal X$), in the narrow sense; or more generally, the dynamics of infection and immunity in the host population;

  2. The adult mosquito population, denoted $\cal MYZ$:

    • mosquito ecology ($\cal M$)

    • mosquito infection dynamics ($\cal Y$)

  3. Aquatic mosquito ecology, denoted $\cal L$

These three chunks are connected by two interfaces. The first two chunks are connected through the rigid interface describing blood feeding and transmission, denoted $\cal B$. The last two chunks are connected through egg laying and emergence, $\cal N, U$.

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

Basic Setup

For our purposes, Basic Setup encompasses the configurable options in xds_setup().

Which model was setup and solved in the demo above? The software supports a modular framework for model building that is highly flexible and extensible. It’s capable of building very capable models, but the software embraces a model-building philosophy of starting simple and adding realism or complexity one step at a time.

The demo model, above, is 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.

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 model family for parasitic infections and immunity in the human population, called $\cal X.$ 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 used instead of the defaults. (The human demographic model, $\cal H$ is set up as an advanced option.)

  • MYZname dispatches a model family for adult mosquito ecology and parasite infection dynamics, $\cal MYZ.$ The setup default model is MYZname="macdonald" and default parameters for the macdonald model are defined in create_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 be used instead of the defaults.

  • Lname specifies a model family for aquatic mosquito ecology, $\cal L.$ 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 be used instead of the defaults.

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 are also configured using xde_setup. In basic setup, 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 framework follows the mathematical formulas and (with small changes) the notation in Wu SL, et. al. 2023

  • nPatches or npn_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 matrix, $\cal N$. Setup sets the value of a variable describing the number of habitats, nqn_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, nhn_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 calK describing mosquito dispersal among the patches.

    • a matrix 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.

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 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.
Figure 3 – The modular structure and extensibility of ramp.xds.