UserGuide

This guide is organized as follows:

• Installing OpenMalaria
• Running OpenMalaria
• Going Forward

You can find the latest releases here (recommended), or you can compile OpenMalaria from source by following the instructions below. To see how to use OpenMalaria, go directly to Running OpenMalaria.

Installing OpenMalaria

You can find the latest releases here, or you can compile OpenMalaria from source (recommended for Linux and Mac users) by following the instructions below.

Compile for Mac, Linux or Windows (using Cygwin)

You will need to install brew on Mac OS or Cygwin on Windows:

Mac OS: If you haven't installed the Homebrew package manager yet, you can do so with the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Windows:

• Install a terminal, either MobaXTerm or Cygwin (Cygwin is preferred if you want to compile OpenMalaria on Windows). If you choose the Portable edition of MobaXTerm, you won't need admin privileges at all. However, Make sure to set a permanent home folder in the settings and restart MobaXTerm. By default, the local terminal operates in a temporary folder and everything you do there will be deleted when you close it.
• Install 7zip to compress uncompress zip files

Install the required dependencies:

# Ubuntu (**requires admin privileges**):
sudo apt-get install git build-essential cmake libgsl-dev libxerces-c-dev xsdcxx libz-dev 

# Mac OS:
brew install git coreutils cmake gcc gsl xerces-c xsd

# Windows (Cygwin):
apt-get install zlib-devel make python2 git cmake libgsl-devel xsd libxerces-c-devel

To install an older version, or to tweak the compilation options, refer to the Expert Guide.

Compile the lastest version:

Now clone the OpenMalaria git repository, and run the build.sh script with the -r flag.

git clone https://github.com/SwissTPH/openmalaria.git
cd openmalaria && ./build.sh -r

The build.sh script is relatively straightforward: it will configure the build system with Cmake, compile OpenMalaria, and create a tarball with all the files that you need. More detailed instructions can be found in the Expert guide.

Your are now free to move and extract the compressed archive (openMalaria-41.0.tar.gz on Linux or openMalaria-41.0.zip in Windows) to any other directory on your system.

Check your installation

The release folder that you have obtained by following the previous instruction (where the openMalaria executable file is located) should contain the following files, plus additional library files depending on your distribution:

$> ls openMalaria-41.0/
autoRegressionParameters.csv  openMalaria               run-example-scenario.sh
densities.csv                 README.md                 scenario_41.xsd
example_scenario.xml          run-example-scenario.bat

Go inside this folder and ask openMalaria to print the version.

cd openMalaria-41.0/
./openMalaria --version

You should see the following output:

OpenMalaria simulator of malaria epidemiology and control.

For more information, see https://github.com/SwissTPH/openmalaria/wiki

	schema version: 	41
	program version:	schema-41.0

OpenMalaria is copyright © 2005-2015 Swiss Tropical Institute
and Liverpool School Of Tropical Medicine.
OpenMalaria comes with ABSOLUTELY NO WARRANTY. This is free software, and you

are welcome to redistribute it under certain conditions. See the file COPYING
or http://www.gnu.org/licenses/gpl-2.0.html for details of warranty or terms of
redistribution.

Printed help; exiting...

If it doesn't, contact [email protected]

If it does, congratulations! You have successfully installed OpenMalaria.

Run your first scenario

An example scenario is provided in the release folder. You can try to run the example_scenario.xml right away:

./openMalaria -s example_scenario.xml

Once the simulation is complete, you will see a new file named output.txt. This file represents model output, which can now be imported into Excel or another data viewer of your choice for analysis.

For more information on output files, see Monitoring.

Running OpenMalaria

Each OpenMalaria simulation is intended to reproduce malaria dynamics in single human population (from approximately village to district scale). This corresponds to a single scenario defined by one input file written in XML (an example input file is here).

OpenMalaria Versions and Schema

OpenMalaria's scenarios are described in an XML document, which must conform to the executable's XSD (Xml Schema Document) version (as of recently running OpenMalaria with the --version command-line option will print the current schema version together with the oldest version which would potentially be compatible). In any case, the schema document relevant to the current scenario (e.g. scenario_23.xsd) must be present, usually in the working directory, when running a scenario.

Usually new schema versions introduce new features, and in some cases no changes (other than increasing the version number) are needed when updating scenarios to a later schema version, while in other cases further changes are necessary. In any case, scenarios can be updated with the SchemaTranslator tool.

Running scenarios via command-line

Before running OpenMalaria one or more scenario.xml files must also be present describing the required simulations. An example scenario is provided in the release folder.

To run OpenMalaria from a terminal on Linux or Mac,

• Open a terminal
• cd to a directory containing the scenario file, .xsd file, and auxiliary files (densities.csv, etc)
• Check that there is no existing output.txt/output.txt.gz or ctsout.txt file
• Run ./openMalaria --scenario MyScenario.xml (or with another path)

Running scenarios via script files

OpenMalaria can be launched using a simple script file which is a list of commands used by the shell/command prompt. This makes it easier to run multiple simulations, with multiple scenarios.xml files.

For Windows, there is an example script called run-example-scenario.bat (make sure you enable explorer options to show file extension, and that it does actually end with .bat):

del output.txt
openMalaria.exe --scenario scenario.xml
pause

For Unix / Linux / Cygwin / MobaXTerm, there is an example script called run-example-scenario.sh:

#!/bin/sh
rm -f output.txt
./openMalaria --scenario scenario.xml
read

The first line in the .sh file (#!/bin/sh) is required to say its a shell script (run by /bin/sh). The next line deletes the old output file using del/rm (we use the -f flag with rm to force it to remove the old file, and not prompt "do you really want to delete ..."). Then we run OpenMalaria: note the name is different, and with unix .sh files we need to prepend it with ./. We give it one option: --scenario which takes one argument, the file name of the input scenario document (you can change the name here; see below for more options). Finally, we use pause/read to make the terminal window running the script stay open until you press return so that you can read any output. A summary of commands:

.sh	.bat	Description
ls	dir	Prints a list of files & directories in the current directory (useful from a command-line)
cd	cd	Change directory
rm	del	Delete a file
read	pause	Something to wait for user input

Scripts can be edited with a simple text/code editor. Make sure the text file is executable by using the command chmod +x script-file.sh.

We recommend the following utilities:

• run.py script — sometimes useful for running test scenarios
• plotResult.py script — provides a quick way to plot outputs from one or a small number of scenarios

Command line options of OpenMalaria

In addition to the normal usage of OpenMalaria (i.e. the --scenario Option), other options are available. The current set of such options can be viewed by running the --help option. The following lists the options available with version 33.

./openMalaria -h
OpenMalaria simulator of malaria epidemiology and control.

For more information, see https://github.com/SwissTPH/openmalaria/wiki

	schema version: 	42
	program version:	schema-42.0

OpenMalaria is copyright © 2005-2015 Swiss Tropical Institute
and Liverpool School Of Tropical Medicine.
OpenMalaria comes with ABSOLUTELY NO WARRANTY. This is free software, and you

are welcome to redistribute it under certain conditions. See the file COPYING
or http://www.gnu.org/licenses/gpl-2.0.html for details of warranty or terms of
redistribution.

Usage: ./openMalaria [options]

Options:
 -V --verbose		Verbose output
 -p --resource-path	Path to look up input resources with relative URLs (defaults to
			working directory). Not used for output files.
 -s --scenario file.xml	Uses file.xml as the scenario. If not given, scenario.xml is used.
			If path is relative (doesn't start '/'), --resource-path is used.
 -o --output file.txt	Uses file.txt as output file name. If not given, output.txt is used.
    --ctsout file.txt	Uses file.txt as ctsout file name. If not given, ctsout.txt is used.
 -n --name NAME		Equivalent to --scenario scenarioNAME.xml --output outputNAME.txt \
			--ctsout ctsoutNAME.txt
 -z --compress-output	Compress output with gzip (writes output.txt.gz).
    --validate-only	Initialise and validate scenario, but don't run simulation.
    --deprecation-warnings
			Warn about the use of features deemed error-prone and where
			more flexible alternatives are available.

Debugging options:
 -m --print-model	Print all model options with a non-default value and exit.
    --print-EIR		Print the annual EIR (of each species in vector mode) and exit.
    --print-interventions
			Print intervention deployment details and exit.
    --print-survey-times
			Print out the times of all surveys and exit.
    --print-genotypes
                        Print out genotype ids and exit.
    --sample-interpolations
			Output samples of all used age-group data according to active
			interpolation method and exit.
 -c --checkpoint	Write a checkpoint just before starting the main phase.
			This may be used to skip redundant computation when multiple
			simulations differ only during the intervention phase.
    --checkpoint-file file	Checkpoint as above. Uses file as checkpoint file name. If not given, checkpoint is used.
    --checkpoint-stop	Checkpoint as above, then stop immediately afterwards. Can be used with --checkpoint-file.
    --debug-vector-fitting
			Show details of vector-parameter fitting. The fitting methods used
			aren't guaranteed to work. If they don't, this output should help
			work out why.
 -v --version           Display the current schema version of OpenMalaria.
 -h --help              Print this message.

Printed help; exiting...

Interpretation of the test scenario

The ctsout.txt contains a table with outputs for "continuous time" the measures specified in the the scenario test.xml. There is one line for each (5-day) time step.

The output.txt contains a table with four columns and no headers.

The first column in output.txt corresponds to surveys. In test.xml, there are 81 surveys, for twenty years, four (quarterly) surveys per year. These are numbered 1 to 81.

The second column in output.txt corresponds to age-groups. In test.xml, two age groups are specified (<5 year olds and 5 to 90 year olds), which are labeled "1" and "2" respectively. There is also a label "0" which is for monitoring measures that do not have an age group (in this case, for a transmission parameter).

The third column has numeric labels for the monitoring measures specified in test.xml. In this example, measures 0, 3, 14, 15 and 36 were monitored. Finally, the fourth column contains the values. For quick interpretation of the output, making a pivot table (e.g. in Excel) can be helpful.

To understand and control the output of the simulation, refer to the MonitoringOptions and OutputFiles page.

Going forward

From now on, learn how to design your own simulations by reading the Scenario Design page.