openmalaria.tools
This is a set of (command line) tools for end users for usage in combination with the openMalaria simulator program from SwissTPH.
No programming experience is required to use these tools.
It contains scripts for
- Plotting openmalaria results with plotResults.py
- Generating Schema Documentation from a provided schema.xsd with generateDoc.py
- Read Output files with readOutput.py (this is used by
plotResults.py) - Reformat XML files with reformat_xmls.py
- translate XML files with translateXML.py
Reasons to implement openmalaria.tools as a separate project from vecnet.openmalaria
- Different license can be used (say user tools can be GPL, while core library can use less restrictive license)
- openmalaria.tools will have a lot of dependencies on other libraries (lxml, mathlibplot and so on). vecnet.openmalaria should have as few dependencies as possible - ideally, none.
- openmalaria.tools is focused on end users, and do not require any programming to be used. vecnet.openmalaria is a library and is intended to be used by python programmers.
- We may have different versioning approaches for vecnet.openmalaria and openmalaria.tools. For example, the tools may have a version number that tracks the newest OM schema version it supports (e.g., OM Toolkit v33.# supports OM versions up to and including version 33). In contrast, the vecnet.openmalaria library should use semantic versioning, and only change its major version when there's a backward-incompatible change to its API.
Tool documentation
Some documentation can be found in the openmalaria wiki.
Result plotting
The plotResults.py script is a tool to quickly plot standard outputs (not the "continuous" outputs) from one or a small number of simulations. Documentation can be found here.
Generating documentation
This tool generates a set of wiki pages from XML Schema Documents (XSD). Here is the output for OpenMalaria schemas.
Usage:
- Change to the directory where you want the output
- Run, giving the path to all schemas of interest (e.g.
/path/to/generateDoc.py /path/to/schemas/schema_*.xsd)
Note that the tool supports only the limited schema features found in OpenMalaria schemas and will likely need extension for any other schema.
XML tools
The script reformat_xmls.py standardises indentation, new-lines and general usage of white-space in an XML file. It is an alternative to xmllint --format. Usage: ./reformat_xmls.py -p folder_path | file_path
Another script, translateXML.py, eases migration of existing OpenMalaria scenarios (XML files) to later versions of OpenMalaria. Usage is simply translateXML.py -t 33 scenario.xml. Full instructions below:
usage: translateXML.py [-h] [-t VER] [-d DIR | -i | --db DBNAME] [-u USER]
[-r RUN_ID] [--mol5d-pairwise] [--add-human-weight]
[FILE [FILE ...]]
This tool translates one or more OpenMalaria scenario files (XML) from one
version to the next.
positional arguments:
FILE A file to translate. Multiple files may be specified.
optional arguments:
-h, --help show this help message and exit
-t VER, --target-version VER
Target version for translation. Default: 33
-d DIR, --dest DIR Destination directory for translated scenarios
-i, --in-place If set, files will be updated in-place (incompatible
with -d option)
--db DBNAME If set, files will be updated from the scenarios table
of this database.
-u USER, --user USER Username to connect to database with. If not set, will
try to connect without username.
-r RUN_ID, --run-id RUN_ID
[DB mode] If given, only scenarios with this run_id
are updated; if not, all are updated.
--mol5d-pairwise Update XMLs using a 5-day time step to use the
Molineaux model with pairwise sampling.
--add-human-weight Add scenario/model/human/weight data to scenarios