Model Building

How To Set Up Models with ramp.xds

This document is a starting point for learning how to build models with SimBA. Some of this material duplicates the vignettes that accompany each R package.

The term model building is overloaded and badly in need of disambiguation. Here, we offer some terminology to help understand model building as an activity to put model bulding with SimBA into context.

Model Building with SimBA

We assume that a user has a well-defined reason for building a model, and that they want to build a model with a defined set of features. Any user could do this on their own – starting with a set of equations and then writing code using basic tools – but the end user would confront the same challenges we did when developing SimBA: the complexity of malaria (and other mosquito-borne pathogens) can become overwhelming; each feature that gets added to a model can create conflicts with other features, some of which are inapparent; and any code would need verification to ensure that it does what it claims to do. More to the point, modifying a model could force a developer to start from scratch.

We developed SimBA to lower the costs of building and implementing models malaria with arbitrary levels of complexity, with the hope of providing a usable tool for malaria analytics. SimBA was designed to help the end user construct a model do an analysis that would be called robust. In this section, we describe how to use SimBA to apply an existing framework and build models of malaria for malaria research and analytics. In the framework below, we call it tertiary model building.

Like all frameworks, SimBA makes a set of design choices that impose a set of constraints. As a framework, SimBA has a modular design that is flexible and extensible to maximize the set of features it could handle. The goal was to develop a model with scalable complexity – the framework was designed to start with simple models and add complexity one step at a time. Our goal was to do this with deterministic systems rather than individual-based simulation models.

SimBA models, developed with ramp.xds, come with a system for setting up models that has identified a large set of features (see Figure) that are handled in two phases: basic and advanced setup.

Figure: A schematic representation of model building in SimBA. The first two columns are handled by basic setup. Features further to the right are handled by advanced setup.

  • Basic Setup uses xds_setup() from ramp.xds, or one of the related setup functions to build a model and set some options (the first columns in the Figure);

    • Choose the model famlies for each one of the dynamical components;

    • Fix some of the basic structural elements of a model: the number of habitats, the number of patches, and the a basic stratification for the human / host population;

    • Set up blood feeding and egg laying.

  • Advanced Setup modifies an xds model object to develop a new model with enhanced features:

    • Set up human demography, including births, deaths, aging, and migration;

    • Stratify the human population on some heterogeneous trait, such as care seeking; housing quality; and heterogeneous biting;

    • Spatial Dynamics

      • Modify the model for time spent and time at risk

      • Modify the model for mosquito dispersal

      • Set up models with indoor / outdoor spaces and house entering

    • Set up a model for exposure with environmental heterogeneity

    • Set up a model for travel malaria or infectious visitors

    • Set up a model in which mosquito resources are hetergeneous over time

    • Malaria Control

      • Set up a model for vector control or entomological surveillance including bed nets, indoor residual spraying, larval source management, attractive toxic sugar baits, or CDC light traps

      • Set up a model with mass medical or therapeutic interventions, including vaccines, mass treatment, etc.

    • Set up a model with weather and modification of mosquito bionomics

    • Set up a model with hydrology, where there is some intermediate variable (e.g. water level) to help set up habitat dynamics

    • Add host species, defined by a biological difference (e.g. bird species as hosts for West Nile Virus) or by the method that handles time spent / time at risk;

    • Add vector species defined as distinct types or by a population dynamic process with genetics.

The guiding principle is that some features build on others, so there is a natural order to follow to make things easier.

Disambiguating Model Building

When people describe model building as an activity, they could mean many different kinds of activities:

  • Primary model building starts with nothing and ends up with a family of dynamical systems. The process goes something like this:

    • start with a basic concept or a phenomenon that needs explaining;

    • doodle on a chalkboard or with pencil and paper to construct a basic flow diagram that translates nebulous concept into something more coherent;

    • translate a flow diagram into a set of states and parameters, and write down the model as a system of differential equations;

    • check the model formulation for internal consistency;

    • do qualitative analysis or numerical analysis; and

    • prove things or visualize things.

  • Model Testing involves model building, but the purpose is to translate a model family into a description of something specific.

    • translate the state variables into observable quantities through a model of the observational process

    • develop a method to estimate the parameters in a model;

    • compare a model to data and evaluate it.

  • Secondary model building starts with a model family and ends up with a calibrated model or another model family:

    • start with a model family and develop a new mathematical model that is simpler or that has enhanced features;

    • develop a framework for model building;

  • Tertiary model building starts with a defined framework for model building and ends with a model to understand some aspect of malaria, done as scientific research, including parameter estimation;

    • Develop a model of malaria using one of the comprehensive individual-based simulation packages: OpenMalaria or eMod or Malaria Tools

    • Build a model using ramp.xds