Skip to contents

ramp.xds - eXtensible Dynamical Systems

Extensible dynamical systems and nimble model building for mosquito-borne disease dynamics.

Install ramp.xds

To install the latest version from GitHub, run the following lines of code in an R session.

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

To get started, see the vignette Getting Started, and the SimBA Project website.

ramp.xds is an R software package that supports Simulation-Based Analytics (SimBA) and Robust Analytics for Malaria Policy (RAMP).

What is RAMP?

Malaria analytics is the systematic analysis of data for decision support or to guide malaria policies. Simulation-based malaria analytics is malaria analytics that uses dynamical systems. RAMP is short acronym for a big idea about how to use simulation based analytics to support iterative malaria analytics and adaptive malaria control.

Malaria involves non-linear interactions among humans, mosquitoes, parasites, and malaria managers that are constantly changing in response to control: it is a kind of complex adaptive system. Lewis Hackett compared malaria to a game of chess:

…malaria is so moulded and altered by local conditions that it becomes a thousand different diseases and epidemiological puzzles. Like chess, it is played with a few pieces, but is capable of an infinite variety of situations.

In other words, malaria systems are locally peculiar: small differences, such as the behaviors of local humans and mosquitoes, can affect blood feeding patterns, transmission, and the responses to control. Malaria complexity, local peculiarity, and systematic changes in response to control create enormous needs for policy, but our ability to fill those needs is limited. Malaria analytics must make the most of limited data. Malaria research & analytics need a systematic way of dealing with complexity, local peculariaty, and uncertainty. This was the seed crystal for RAMP.

RAMP was developed as a way of dealing with the uncertainty. We can’t wish away the uncertainty, but we can do our best to characterize and quantify uncertainty and propagate the uncertainty through analytics pipelines we use to develop policy. Robust analytics have gone to great lengths to ensure that the advice would not change if the analysis had been done in another reasonable way.

This software, called SimBA (short for Simulation-Based Analytics), was developed as a practical way of developing robust, simulation-based analytics for malaria. Managing malaria involves a large set of linked activities, and some of these come with a heavy computational or quantitative load: data processing and curation; conventional statistical analysis; scenario planning; and strategic planning. Simulation based analytics – the application of dynamical systems models of malaria transmission dynamics and control in malaria analytics – play a key role through seamless integration of retrospective data analysis, real-time decision support, and evidence-based approaches to setting rational expectations about the future. SimBA lowers the costs of doing all this robustly.

The SimBA project (Simultation-Based Analytics) is a suite of software packages that have the goal of supporting routine malaria analytics:

  • It was designed to enable nimble model building.

  • The models play a role in developing malaria intelligence – a quantitative assessment of malaria built for policy evaluation.

  • The software was designed for iterative engagement: the models can be reused and they can be modified.

  • The software was designed for robust analytics; it is comparatively easy to build suites of models that cover the uncertainty, and functions enable development of analytics pipelines to propagate uncertainty.

  • The software was designed for accountability; the analysis is transparent.

By nimble, we mean a lot of things. One of them is that software lowers the costs of setting up, solving, analyzing, and applying dynamical systems to model the mosquito ecology or the epidemiology, spatial transmission dynamics, and control of malaria and other mosquito-transmitted pathogens.

A core goal is to understand malaria transmission in terms of a changing baseline (using ramp.forcing to model the effects of weather, hydrology, …) that is modified by vector control (using ramp.control).

What is SimBA?

This package, ramp.xds handles core computation for a suite of six software packages that support simulation-based analytics. SimBA describes the collection.

SimBA includes ramp.xds and all its satellite packages (below).

SimBA has been designed to serve the needs of malaria programs, where mathematical models are used for decision support and adaptive malaria control in a defined geographical area. Mechanistic models that have been fitted to data describing malaria in a place provide a synthesis of malaria intelligence. These models can facilitate complex analysis, extending our innate mental capabilities. By characterizing and quantifying uncertainty, and then propagating the uncertainty through the analysis, simulation-based analytics serve as a platform for giving robust policy advice and for adaptive malaria control. As the needs of a malaria program changes, the models can be modified – simplified or extended – to serve the tasks at hand.

ramp.xds does core copmutation: the software makes it easy to build and solves dynamical systems and outputs the predicted values of standard, observable malaria metrics. It also provides some computational support for qualitative analysis: it computes steady states, stable orbits. In ramp.work, we developed algorithms that fit models and evaluate vector control; that develope short term forecasts; and that enable scenario planning and strategic planning.

Originally, ramp.xds was a single program, but it made sense to split the software into several R packages. When it split, we started using calling the software development project SimBA. In the narrow sense, SimBA software includes six distinct R packages:

  1. ramp.xds handles setup, solving, plotting, and some analysis. It was developed to build and solve dynamical systems models for the epidemiology, transmission dynamics, and control of malaria and other mosquito-transmitted pathogens based on a well-defined mathematical framework. It includes a basic set of models – enough to design, verify, and demonstrate the basic features of modular software.

  2. ramp.library is an extended library of models – stable code that has been tested and verified. It includes a large set of model families published in peer review that are not included in ramp.xds The ability to reuse code reduces the costs of replicating studies. Through this library, ramp.xds also supports nimble model building and analytics for other mosquito-borne pathogens.

  3. ramp.control is a collection of disease control models for ramp.xds

  4. ramp.forcing is a collection of utilities to model exogenous forcing in models for ramp.xds

  5. ramp.demog is is a supplementary code library for ramp.xds that handles human demography and stratification, including vital dynamics and age structure.

  6. ramp.work includes algorithms to apply the framework, include code to fit models to data and to do constrained optimization

ramp.xds is under active development. It supersedes two other software packages, no longer under active development: exDE and MicroMoB. The history of development of RAMP simulation software has been memorialized in a vignette.

The material in this website supports ramp.xds development and a basic introduction.

Contributing

ramp.xds aims to provide stable, reliable, reusable code for the study of mosquito-borne pathogen dynamics and control using dynamical systems. For information about how to contribute to the development of ramp.xds, please read our article on Contributing.

If you have any questions, comments, bug reports, or suggestions, the first point of contact with the development team is through GitHub Issues. If you are specifically submitting a bug report, please check out our bug reporting guide. If you are interested in collaborating in extensive model development (e.g. new mosquito model), please do not hesitate to contact the authors, whose email addresses can be found in the DESCRIPTION file.

We welcome issues and encourage contribution regardless of experience; the length of the contributing guide is not intended to be intimidating, merely complete. It is the responsibility of the package maintainers to help new contributors understand our conventions and guide contributions to a successful conclusion.

Acknowledgements

  • This project was supported by a grant from the Bill and Melinda Gates Foundation, Modeling for Adaptive Malaria Control (INV 030600, PI = David L Smith, University of Washington).

  • Support for Adaptive Vector Control is funded by grant Spatial Targeting and Adaptive Vector Control for Residual Transmission and Malaria Elimination in Urban African Settings (R01 AI163398, PI = David L Smith), from US National Institute of Allergies and Infectious Diseases (NIAID).

  • Development of SimBA, RAMP and Adaptive Malaria Control was supported through collaboration with the Bioko Island Malaria Elimination Program and Uganda’s National Malaria Control Division and Department of Health Information in the Uganda Ministry of Health

  • Development of this software benefited from funding and collaboration with the NIAID grant Program for Resistance, Immunology, Surveillance & Modeling of Malaria in Uganda (PRISM) (2U19AI089674, PIs = Grant Dorsey, University of California San Francisco; and Moses Kamya, Infectious Diseases Research Collaboration), which was part of the International Centers of Excellence in Malaria Research (ICEMR) program.

  • Funding to develop models of West Nile Virus to support Harris County Public Health was funded by the NSF as part of a project, Computing the Biome (PI = Janos Sztipanovits). The project was part of the Convergence Accelerator program of the National Science Foundation, Directorate for Technology, Innovation, and Partnerships (TIP) (NSF 2040688 and NSF 2040688, PI=Janos Sztipanovits, Vanderbilt University).

  • We also acknowledge the importance of the mosquito working groups of RAPIDD (Research and Policy for Infectious Disease Dynamics), which was sponsored by the Fogarty International Center, NIH, and the Department of Homeland Security. The mosquito working groups were led by Professor Thomas Scott. RAPIDD was directed by F. Ellis McKenzie.