ScenarioDesign
Each OpenMalaria simulation corresponds to a single scenario defined by one input file written in Extensible Markup Language (XML). Using models to make predictions usually involves running many distinct simulations to compare the effects of changes in model structure or parameters. This section considers only how to set up a single simulation (scenario). If you want to design an experiment evaluating the impact of one of more factors, and hence running many scenarios, you may want in addition to read about designing experiments.
The main input to the simulator is a file generally called scenario.xml (though it may be named something different if the --scenario FILE command-line option is passed to OpenMalaria).
XML configuration files can be edited by a text editor — see here.
To understand the structure of OpenMalaria scenarios, copy one of the scenario.xml documents from the snippet library linked above (e.g. v32). It should have this layout:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<om:scenario name="example" ...>
<demography .../>
<monitoring .../>
<interventions .../>
<healthSystem .../>
<entomology .../>
<parasiteGenetics .../> <!-- only in v33+ when modeling drug resistance -->
<diagnostics .../> <!-- only in v33+ and not required -->
<pharmacology .../> <!-- only needed when modeling drugs with 1-day time-step models -->
<model.../>
</om:scenario>The XML file has several sections corresponding to specific model blocks. The primary element in the XML file, called "scenario", encapsulates everything else in the file, except the XML header line and is described below. Detailed documentation of each of the other components and how they are configured can be found by following the links in the following table:
| XML element | Content | Description |
|---|---|---|
<model.../> |
Models of malaria dynamics in the absence of interventions | Parameterised with data from field studies |
<demography .../> |
simulated human population size and age distribution | |
<entomology .../> |
The assumptions about exposure to infective mosquitoes and Transmission from humans to mosquito | Setting specific details including seasonality and vector characteristics |
<healthSystem .../> |
The assumptions about case management | i.e.treatment seeking, coverage etc. |
<interventions .../> |
The assumptions about Interventions | (e.g. administering vaccines, deploying bed nets or changing the health system) |
<parasiteGenetics .../> |
Option from v33+ only | |
<diagnostics .../> |
Diagnostic tests in use | Option from v33+ only |
<pharmacology .../> |
Pharmacokinetics and Pharmacodynamics | Option from v33+ only |
<monitoring .../> |
The required outputs from the simulation | what data is returned, how it is categorised. |
In addition, the automatically generated schema documentation for each version of OpenMalaria provides a full description of the syntax for the scenario files. The key to the syntax of this document is:
Key:
abc one and only one instance of this element/attribute is required
[ def ] optional (zero or one element/attribut may be present)
( ghi )* any number (zero, one or more elements/attribute(s)) may be present
( jkl )+ at least one element/attribute must be present
( mno ){2,inf} two or more occurrences are required
where the letters abcdefghijklmno represent the name of the XML element or attribute.
It has the following attributes:
| attribute | data type | purpose |
|---|---|---|
| schemaVersion | int | Version of XSD schema to use; should correspond to one of the scenario_VER.xsd files in test
|
| analysisNo | int | |
| name | string | user-friendly name for the scenario |
| wuID | int | BOINC workunit number (automatically set when needed) |
| assimMode | 0 or 1 | removes 3 columns from output.txt for BOINC usage (use 0 for local scenarios) |
Constructing scenario files from scratch can be challenging. You can view our base scenario here. A library of XML snippets contains templates and parameters useful in creating scenarios and should be used as templates for any specific application.
The test scenarios which can be used both as template scenarios and to check that OpenMalaria is working as usual. If you have downloaded the binary from the binary archive then you have also downloaded a folder of these tests. Note that the test scenarios include many non-default options which will mostly need to be removed if the XML is used a template for simulating malaria in the real world. The centre scenario from Briët et al., 2012 is a good starting point. The construction of a complete scenario file then entails checking that the correct XML code is included for each module of the program.
If you have built OpenMalaria from source, all of its test scenarios can be run via the RUN_TESTS build target (IDEs), by running make test, with ctest, or with custom settings via the test/run.py script. These tools are mostly aimed at testing the OpenMalaria executable and are documented on the Expert Guide.
OpenMalaria can simulate a steady-state of malaria transmission (with or without health system coverage), followed by one or more interventions and monitoring over a follow-up period. It is less good at simulating low levels of transmission and when historical transmission does not follow some consistent seasonal pattern.
Simulations have essentially two phases: a warm-up phase which is used to initialise human-immunity models (by simulating a whole lifespan of transmission) as well as transmission models, and an intervention phase during which interventions may be deployed and the results monitored. OpenMalaria automatically handles the warm-up phase, while events in the intervention phase are determined by configuration of interventions and monitoring surveys. More details on time...
The OpenMalaria simulator uses discrete time step updates of one and/or five days, resulting in 365 or 73 steps per year.
The diagram below gives a high-level view of the processes abstracted into a model. All model-specific behaviour is abstracted into one block, or model component. More detailed graphs restricted to the components of interest are available on some of the sub-model pages.
Color key: green arrows increase a quantity, red arrows decrease a quantity. Shape key: oval nodes are processes affecting something, boxes surround models, and hexagonal nodes are quantities without a process in view of the diagram.
Some perspectives for looking at model processes are those of human population processes or of mosquito population processes.
A common perspective is that of the malarial infection cycle. The following graph shows the cycle assumed by the model. Blood-stage parasite densities are one of the most important aspects here. The effects of interventions are not shown.
This documentation is intended to aid individuals modifying existing scenario files:
Describes the population size and age structure. Most of our scenarios use the same age-structure data from Ifakara, Tanzania. Adjusting the population size is useful, since it has a major impact on run-time and stochasticity of results (1000-100000 individuals are often used in experiments; testing scenarios often use less).
The monitoring element is used to describe two types of output: continuous (or at least regular) reporting of single values, and survey data, which may be irregular and is usually sub-divided by age-group or another differentiator.
Details on the Monitoring system and on configuring monitoring.
The continuous and SurveyOptions elements describe which outputs to enable for the two outputs, using a list of sub-elements of the form <option name="NAME" value="true"/>; lists of valid options are below.
Tables of continuous and survey measures.
Continuous reporting, when enabled (a continuous element is described and period is positive), outputs data every period days (period is an attribute of the continuous element).
This output normally starts from the beginning of the intervention period, but for diagnostic purposes it can be enabled from the beginning of initialization by including a duringInit="true" attribute. This has two additional side effects: an extra column, simulation time, is output as the first column, and where period is greater than the length of a timestep, reporting (during intervention period) may happen on different timesteps.
The surveys element has a list of surveyTime sub-elements, each with the timestep of a survey, starting from 0, the start of the intervention period (numbers match timesteps at which interventions can be deployed). A survey at time x takes place at the beginning of that timestep, so, for example, if the first survey has time 73 with a 5-day timestep, it covers exactly the first year of the intervention period.
Timestep 0 will always correspond to the first of January (up to 5th Jan with a 5-day timestep), except that, prior to schema 22, when the maximumAgeYrs attribute of demography was not a whole number of years timestep values may well have been offset. Years are always modelled as 365 days long, hence (n * 365 / days_per_timestep) is always the beginning of the n-th year of the intervention period (excepting above offset).
Note: The largest surveyTime sub-element value determines the length of the intervention period (and thus the number of post-warmup time steps that the simulation will run; see Model Time Updates.).
The ageGroup element contains a list of group sub-elements, each of which has an upperbound attribute. These (and the lowerbound attribute of ageGroup) define the age-groups which reports are divided into. The age-group specified in output data is the index within these groups, ordered by age (youngest to oldest), with the first age-group having index 1.
PK and PD parameters of drugs can be specified.
Finally, scenario contains a model element, grouping some of the data describing the "model" together.
The ModelOptions sub-element is a list of binary options, in the same format as SurveyOptions (except here, bug-fix options default to true if not specified, while the rest still default to false). A list of available options can be found on the WithinHost page.
The clinical element currently simply has a healthSystemMemory attribute: if, when a sickness bout occurs, the previous episode was less than or equal to this many time-steps ago, the new bout is considered a second case (second-line treatment may be used and the two bouts will likely be reported as a single episode). The healthSystemMemory is defined in time steps. In the 5 day model, a value of 6 corresponds to 30 days.
(The main description of case management is within the [<healthSystem> element] (ScenarioHealthSystem).)
| Download openmalaria | Installation instructions | XML Schema Documentation |
| XML Schema Version | Program version | master |
develop |
|---|---|---|---|
| 43 | schema-43.0 |
 |
 |