SchemaUpdateGuide

Recent versions

In most instances of recent versions, schemas are backwards-compatible, i.e. you only have to update the version numbers at the top. Schema translation tools have not been updated.

Version 46.0

• Progress information is disabled by default. Use the new --progress command-line option to enable it instead.
• The parameter used to make a decay function increase has been renamed from complement to increasing
• Minimum monthly EIR has been set to 1% of the maximum monthly EIR (nothing to do but be aware that using this version might produce slightly different results)

Version 45.0

The --deprecation-warnings command-line option has been removed. Warnings are now shown by default. Instead, you can use --no-deprecation-warnings to hide them.

Version 44.0

Backward-compatible with version 43, no changes required.

Version 43.0

propActive can be used again, but it can only be set to either 0 or 1. Any other value will result in an initialization error.

Version 42.0

propActive is no longer supported and is automatically forced to 1. To combine interventions, and in the situation where you want an all-over-the-night parameterisation (because some interventions are effective only part of the night time, e.g. LLINs which are effective only when the individual is in bed), the current workaround is to set propActive=1 and reduce the efficacy parameters (PA, PB, PC), possibly using several cohorts/GVIs if necessary.

Version 40.0

This version introduced backwards-incompatible changes to the PK/PD parametrisations and to specification of normal and log-normal distributions.

Since LSTM have been testing and updating their parametrisations over the same time period, we recommend updating to the more recent version of the pharmacology snippet [not yet published].

The following table gives examples of how XML elements may need to be updated. In general, a mean attribute is required, while distr and SD (standard deviation) or CV (coefficient of variance) are only required for non-zero variance.

Location	old version	new version	notes
Entomology	<availabilityVariance value="0"/>	<availability/>	Special case: mean is not used. In this example there is no variance.
ITN description	<initialInsecticide mu="70" sigma="20"/>	<initialInsecticide mean="70" SD="20" distr="normal"/>
ITN description	<insecticideDecay L="2.2" function="exponential" mu="-0.32" sigma="0.8"/>	<insecticideDecay L="2.2y" function="exponential" CV="0.946826741968"/>
ITN description	<holeRate mean="0.9" sigma="0.8"/>	<holeRate mean="0.9" CV="0.946826741968" distr="lognormal"/>
ITN description	<ripRate mean="0.7" sigma="0.8"/>	<ripRate mean="0.7" CV="0.946826741968" distr="lognormal"/>
Pharmacology / PD	<IC50>0.02</IC50>	<IC50 mean="0.02"/>
Pharmacology / PD	<vol_dist>300</vol_dist>	<vol_dist mean="300"/>
Pharmacology / PK	<k mean="0.1" cv="1" distr="lnorm"/>	<k mean="0.1" CV="1" distr="lognormal"/>
Vivax	<firstRelease mu="4.5294379" sigma="0.956" latentRelapseDays="10"/>	<firstReleaseDays mean="14.6" CV="1.22" distr="lognormal" latentRelapse="10"/>
Vivax	<bloodStageLengthDays weibullScale="115.0582" weibullShape="2.331"/>	<bloodStageLengthDays scale="115.0582" shape="2.331" distr="weibull"/>

Note that log-normals are now parametrised via CV (coefficient of variance, linear space), not sigma (log-space standard deviation). To convert:

sigma = sqrt(log(1 + CV*CV)) CV = sqrt(exp(sigma*sigma) - 1)

From schema-version 32 on

Use this python script to translate old scenario XML's: translateXML

(By @tph-thuering), Need to be updated

Before schema-version 32

Note: The following instruction are outdated

Automatic schema version update

If you use some scenarios working with an older schema version, these can be updated with the schema translator. The translation may not work for all scenarios, but it will point out the area where it detects an ambiguous situation, by either asking you to specify the value of a certain flag and then rerun the translator, or by pointing out where a manual edit in the scenario is required.

The schema translator can be used within openmalariaTools or as a stand-alone tool. Alternately ask your local software developer for help.

Stand-alone

You need Java version 7 or later (open a command prompt: does java -version or java.exe -version work and tell you it is version 7 (or 1.7) or later?). Then either checkout the OpenMalaria code and go to the util/SchemaTranslator directory or download the jar files from this directory (optionally also a schema (.xsd) file). Create a scenarios directory and put the XML files there. Then run something like java -jar bin/schema-translator.jar --help.

You will likely need to either use --no-validation or --schema-folder PATH (substituting PATH with the location of the directory where the XSD file is). You may be asked to specify other options when you try running the tool; if so just add them to the command line and try again (no need to remove existing translated scenarios first).

Build and Install

Building the schema translator from sources:

1. Check if JDK of at least version 5 is installed. * If it's not the case, download OpenJDK or Oracle's JDK
2. Install the Kotlin compiler (version 0.5.748 in my case)
3. Find the sources. * Clone the OpenMalaria source code, then find the schema translator source files in util/SchemaTranslator
4. Build the sources. * in the sources folder do ./compile

Usage

1. Put the scenarios to be converted in the scenarios folder (sub-folders are fine too — directory structures are preserved)
2. Run the program from terminal or command line with the command java SchemaTranslator * If running from another location, use java -classpath path_to_schematranslator_folder SchemaTranslator * other options can be used if necessary, as below
3. Check warning/error messages in the program's output
4. Use updated scenarios from the translatedScenarios folder

If you don't add any options, then the scenarios will be converted to the latest schema version.

Options

Below are some of the most useful options. To see a full list, run the schema translator with the help option: java SchemaTranslator --help

• --required_version XX: The version number to update the scenarios to. By default, the latest schema version will be used.
• --current-schema --schema-folder ../../build/schema: update to the latest development schema, which is at ../../build/schema/scenario_current.xsd
• --no-validation: if no xsd file is available, scenarios can still be translated with this option but standard XML schema checks can't be done
• --maxDensCorrection BOOL: Update 12->13 requires this sometimes: set true to include bug fix, false to explicitly exclude it.
• --iptiSpOptionWithoutInterventions: For scenarios with iptiDescription but without interventions, assume usage of the IPTI model was (t) intended or (f) a mistake.