Skip to contents

Basic Setup

Source: vignettes/BasicSetup.Rmd
BasicSetup.Rmd

Previous: Getting Started & Working with Models

Also, see SimBA

In the vignette Getting Started, we introduced xds_setup. In this vignette, we take a deeper dive into Basic Setup (also, see the help documentation xds_info_basic_setup).

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 Problem

  • Set up the Model Structure

  • Configure the Dynamical Components

  • Spatial Dynamics

  • 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

Each one of the dynamical components can be implemented by one of several different modules. For each component, one of those modules is called 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. To focus on one component, the trivial modules are configured to pass inputs.

Using trivial modules, it is possible to develop models that isolate and study part of a full system.

The Dynamical Frame

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

Model Structure

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.

Structural Parameters

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:

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\; S(t)\; T(t) \; K(t)\] where + \(m\) - is the mean + \(S(t)\) or F_season outputs a seasonal pattern + \(T(t)\) or F_trend outputs a trend + \(K(t)\) or F_shock outputs a perturbation

These functions are set up using a built-in function maker called make_function.

Spatial Dynamics

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

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.