Basic Setup

Previous: Getting Started & Working with Models

Also, see SimBA

---

In the previous vignette Getting Started, we introduced xds_setup. Here, we take a deeper dive into Basic Setup.

Inline help is also available through:

?xds_basic_info

which is also viewable as html.

ramp.xds is based on a mathematical framework for model building that is modular, flexible and extensible. Using setup 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.

Overview of Setup

Progressive model building starts with basic setup. To set up a model, the user needs to:

• Frame the Model

• Set up the Model Structure

• Configure the Dynamical Components

Other options we consider as an extension of basic setup are:

• Set up or modify forcing for any Trivial Components

• For spatial models, configure

  • Mosquito Dispersal

  • Time Spent / Time at Risk

• Scalable Complexity

The xds Model Object

To use ramp.xds a dynamical system is encoded in the xds object. Basic setup builds an xds object, or xds_obj:

• xds_obj is a compound [list], and class(xds_obj) == "xds_obj"

• Other objects are attached to xds_obj:

  • objects that define the dynamical system, including parameter values, indices for the variables, and initial values of the variables

  • objects that define the dynamical interfaces that pass information among components

  • the dynamical terms computed by the interfaces

  • the orbits and other outputs of solving the system

  • ports and junctions to add new features

Build a Model

To use ramp.xds at all, the xds object must be properly formatted and configured, but it was not feasible to do this all at once. Instead, the software envisioned model building in two phases: basic and advanced.

Basic Setup is defined by xds_setup, a function that builds a fully defined xds object and configures a minimal set of elements. Various partially defined models are also built through basic setup (see Framing the Problem).

Advanced Setup handles advanced features, including exogenous forcing, vector control, and other modes of malaria control, human demography and aging, and host population stratification (see Scalable Complexity).

Framing the Problem

The first step in any study is to frame the problem. When that problem involves building and solving a dynamical system, framing the problem involves an iterative process of asking and reasking a question until it is in a form that can actually be answered. The starting point is often a general question that could spark broad philosophical discussions. Framing involves refining the question until the shape of the answer is well-defined.

ramp.xds was designed to lower the costs of answering questions that would benefit from building and solving a dynamical system model of a mosquito-borne pathogen dynamics in populations. To understand the process of translating a question into a basic setup algorithm, it’s useful to know a little about modular computation in ramp.xds, the concepts of modularity and trivial modules, and the dynamical frame.

Dynamical Components

Dynamical systems for malaria and other mosquito-borne diseases are made up of three core dynamical components that describe five core processes.

• XH - a system of equations describing two inextricably linked processes:

  • X - the dynamics of host infection and immunity

  • H - human / host demography and behavior

• MY - a system of equations describing two inextricably linked processes:

  • M - adult mosquito ecology

  • Y - parasite / pathogen infection dynamics in mosquitoes

• L - a system of equations describing immature mosquito ecology

A generic interface makes it possible to add other variables (see Scalable Complexity, below)

Dynamical Interfaces

Information is passed among components by two interfaces:

• The X and Y components interact through the XY Interface. It handles:

  • blood feeding,

  • parasite transmission; and

  • exposure.

• The M and L components interact through the ML Interface. It handles:

  • the locations of the aquatic habitats,

  • emergence of adult mosquitoes from aquatic habitats; and

  • egg laying.

Trivial Modules

For each component, it is possible to set up choose the trivial module. The trivial modules ignore the inputs that come from other dynamical components, and they pass the component’s outputs from a trace function. Using trivial modules, it is possible to develop models that isolate and study part of a full system.

• The trivial L module outputs the daily emergence rate of adult, female mosquitoes in each patch (\(\Lambda\))

• The trivial MY module outputs either:

  • The egg laying rate by the mosquito population in each patch (\(G\)); or

  • The net human blood feeding rate of the adult mosquito population (\(fqZ\))

• The trivial X module outputs net infectiousness (\(\kappa\))

Using xds_setup_eir(), it is possible to set up a trace function that passes the EIR to the XH component.

Trace Functions

The functions that output these terms are composed time series functions, with four components:

• a mean (or scaling) parameter whose name depends on the forcing term

• a seasonality pattern, F_season(t, V)

• a trend, F_trend(t, V)

• a shock function, F_shock(t, V)

Each function requires a second argument, V, from the function get_variables that dispatches on season_par, trend_par or shock_par. By default, these are empty lists, and get.variables.list returns an empty list. The default functions F_season, F_trend, and F_shock ignore V and return a constant value \(1.\) The packages ramp.func and ramp.forcing have utilities that make it easy to set up forcing.

The Dynamical Frame

A flowchart to determine which version of xds_setup to use.

---

If the MY component is not trivial, then it will need inputs from the other two components, so a full system will need to be configured. If, on the other hand, the M or Y component is trivial or unnecessary, then either the L Component or the XH component is completely redundant.

To set up and solve partial systems, the xds object defines a frame, and class(frame) dispatches functions that solve the systems and parse the outputs.

The dynamical frame is the All xds_setup_* functions define xds_obj$frame and the functions used to solve and parse differential equations use the S3 system, with methods that dispatch on class(xds_obj$frame).

• xds_setup (frame="full") sets up all three components.

• xds_setup_mosy (frame="mosy") sets up models for mosquito ecology:

  • the model includes an L component
  • the model has an M component but no Y component (eg basicM)
  • a trivial H module can be configured
  • the X component is not used

• xds_setup_aquatic (frame="aquatic") sets up models of aquatic mosquito ecology:

  • a trivial MY component is configured for egg laying
  • the XH component is not used

• xds_setup_human (frame="human") sets up models to study epidemiology

  • a trivial MY component is configured for infectious biting in patches
  • the L component is not used

• xds_setup_eir (frame="eir") sets up models to study epidemiology

  • a trace function computes the EIR, denoted
  • the MY component is not used
  • the XH component is not used

Structural Parameters

Model structure has two main parts:

• Malaria Landscapes — a spatial domain is subdivided into patches that define adult mosquito populations and the aquatic habitats to handle ecological heterogeneity and parasite transmission

• Stratification — the process of segmenting a human population into strata to handle epidemiological heterogeneity. Some degree of stratification is made necessary to deal with features of the malaria landscape.

The model structure is characterized by several core parameters. The values of these parameters are set during basic setup:

• nPatches or \(n_p\) — the number of patches in the model.

• nHabitats or \(n_q\) — the number of habitats in the model

• membership — a vector describing patch membership of the habitats

• nStrata or \(n_h\) — is the number of human / host population strata

• residence — a vector describing the index of the patch where a stratum resides

• nVectorSpecies — the number of vector species

• nHostSpecies — the number of host species

The following discusses how these are configured during setup.

Dynamical Components

The modules for the dynamical components are assigned by three arguments:

• Xname — the name of an X module (see XH_module_list)

• MYname — the name of an MY module (see MY_module_list)

• Lname — the name of a L module (see L_module_list)

XH Component

The XH component handles both the X and H components. They are designed to handle different processes, so they are handled differently.

X

The X component defines a set of state variables to model disease dynamics: the base model is developed for a single homogeneous population.

• Xname dispatches setup functions that configure the X component ( See XH_module_list for a list of modules).

• the default is Xname = "SIS"

• HPop is a required argument

• If nPatches>1, a residence vector should be passed:

  • length(HPop) = length(residence)

  • a time spent matrix should be set up

  • blood search weights can be set by argument .

H

The H Component is defined by two ports:

• Births – a function that adds individuals to the population.

• D – a linear demographic operator that handles mortality and flows among strata

Basic Setup sets up no effect models by default (no births or deaths), and trivial forcing.

Complexity and realism are added through a process called principled stratification. The state variable vector is replicated across multiple strata to handle:

• epidemiological heterogeneous parameters

• human age and cohort dynamics

• migration

Advanced setup options for the H component, including principled stratification are in ramp.demog.

MY Component

Basic setup for the MY component

• MYname dispatches setup functions that configure the MY component ( See MY_module_list for a list of modules).

• the default is MYname = "SI"

L Component

Basic setup for the L component

• Lname dispatches setup functions that configure the L component ( See L_module_list for a list of modules).

• the default is Lname = "trivial"

Trivial Modules

The trivial modules configure trace functions to pass outputs. The trace functions are designed around the concept of a constructed time series with the form: \[ m\; F_S(t)\; F_T(t) \; F_K(t)\] where

• \(m\) - is the mean

• \(F_S(t)\) or F_season outputs a seasonal pattern

• \(F_T(t)\) or F_trend outputs a trend

• \(F_K(t)\) or F_shock outputs a perturbation

For a longer introduction, see SimBA:Trace Functions

Spatial Dynamics

• If nPatches >1 then other setup-configurable options are to pass:

  • Values for the search weights (see search_weights)

  • Options to set up the mosquito dispersal matrix, \(K\) (see mosquito_dispersal)

  • Options to set up a time spent matrix, \(\Theta\) (see 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.