Basic Setup

library(ramp.xds)

Basic Setup includes any option that can be configured with xds_setup family of functions. Basic setup is used to set up a basic frame:

Dynamic Components

A first step is to choose the modules / model families. There are three COMPONENTS:

  • A model for the dynamics of infection and immunity in the human / vertebrate host population – the X part of the XH component – is specified by passing an argument to Xname.
sis_mod <- xds_setup(Xname = "SIS")

  • The model for human demography / host ecology – the H part of the XH component – is initially set to a trivial model with no vital dynamics. Human demography is configured later.

  • A model for the adult mosquito ecology and infection dynamics, called the MY component, is specified by passing an argument to MYZname. For example:

macdonald_mod <- xds_setup(MYZname = "macdonald")
  • A model for the aquatic mosquito ecology, called the L component, is specified by passing an argument to Lname. For example:
aqua_mod <- xds_setup(Lname = "basicL")

If no names are provided, then xds_setup() uses the defaults:

  • Xname = "SIS"

  • MYZname = "macdonald"

  • Lname = "trivial"

Interfaces

The interface for the model is built around a patch-based spatial dynamics (i.e., metapopulation dynamics) with a flexible structure. A few structural parameters define how the rest of the model gets set up, and then the algorithms that compute blood feeding and transmission and

Structural Parameters

Every model has three basic structural parameters:

  • nPatches or \(n_p\) is the number of spatial patches. By default nPatches=1. To specify a different number of patches, an argument is passed to xds_setup():
mod_with_2patches = xds_setup(nPatches=2)
mod_with_2patches$nPatches 
[1] 2
  • nHabitats or \(n_q\) is the number of aquatic habitats. The parameter can not (and should not) be set from the command line. Instead, the habitat membership vector is passed that gives the index of the patch (an integer) where habitat is found. If the first patch has 1 habitat, and the next patch has 2, then membership \(=c(1,2,2)\) and nHabitats\(=3\):
mod_with_3habitats <- xds_setup(nPatches=2, membership = c(1,2,2))
mod_with_3habitats$nHabitats
[1] 3
  • nStrata or \(n_h\) is the number of human population strata. The number can not (and should not) be set from the command line. Instead, the human population size HPop is passed as a vector of values and nStrata\(=\mbox{length}(\)HPop\()\). If nPatches\(>1,\) then a residence vector must be passed that gives the index of the patch (an integer) where each population stratum resides. It must be true that \(\mbox{length}(\)residence\()=\)nStrata and that max(residence)\(\leq\)nPatches.
mod_with_3strata <- xds_setup(nPatches = 3, 
                              HPop = c(300, 100, 200), 
                              residence = c(2,3,3))
mod_with_3strata$nStrata
[1] 3

If nPatches is set to a value larger than one, then the user should also pass arguments to set up mosquito dispersal, and human time spent/time at risk. To configure these elements using xds_setup(), see Spatial Dynamics.

Blood Feeding and Transmission

Most features of the interface for blood feeding and transmission are configurable; some of those options can be configured at basic setup, while others will need to be

The search weights for human population strata used in the blood feeding intervace can be set in xds_setup() by setting the values of searchB where \(\mbox{length}(\)searchB\()=\)nStrata.

Egg Laying and Emergence

The search weights for human population strata used in the blood feeding interface can be set in xds_setup() by setting the values of searchQ where \(\mbox{length}(\)searchQ\()=\)nHabitats.

Plug and Play Modularity

The software was designed to be modular with plug-and-play functionality. The interfaces set a rule for passing information among components, but we also wanted to be able to set up models where it was possible to study each one of the components or combinations where the inputs from other components were known. Each one of the modules can thus be reduced to a trivial model; at setup, a function – called a trace function – is configured to compute the outputs required by other components.

When any one of the modules is trivial, the outputs of that model are configured in a particular way, described in Trace Functions.

If the MY component is trivial, then we must choose to ignore either the XH component or the L component. To handle setup and computation for these special cases, the xds object is assigned a frame that dispatches methods to solve the appropriate sets of equations:

  • xds_setup() – sets up a full model.
class(sis_mod$frame)
[1] "full"
  • xds_setup_human() – sets up a trivial MY component that passes the net blood feeding rates of infectious mosquitoes. If there is more than one patch, the model must set up a time spent matrix. These models lack an L component.
class(xds_setup_human()$frame)
[1] "human"
  • xds_setup_mosy() – This sets up a model that lacks an XH component. It also lacks the Y part of the MY component as a way of studying vector ecology without infection dynamics.
class(xds_setup_mosy()$frame)
[1] "mosy"
  • xds_setup_aquatic() – sets up a trivial MY component that passes habitat-specific egg laying rates. The model lacks an XH component.
class(xds_setup_aquatic()$frame)
[1] "aquatic"
  • xds_setup_cohort() – this model sets up the XH component, but it lacks an MY component and an L component. Instead, it configures a function \(F_E(a,t, \tau)\) that computes the daily EIR for a cohort of humans born on day \(\tau\) as it ages (\(a\)) over time (\(t\)). For more, see Cohort Dynamics.
class(xds_setup_cohort()$frame)
[1] "cohort"

All of the following explain the options for xds_setup(). With some minor exceptions for xds_setup_cohort(), all setup functions follow the same conventions.