Changelog

OpenMalaria releases

Below is a list of the most significant changes in each release, together with the date and revision number of initial release. Releases are available here.

Schema 46.0 release

This release focuses on improving the simulation of heterogeneity via availability of humans to mosquitoes (the <availability/> parameter in the vector model) and improving decay functions (see below).

Progress information is now disabled by default for performance

• Use the new --progress command-line option to enable progress output

The minimum monthly EIR value is set to at least 1% of the maximum monthly EIR value (previously 0.1% of the annual EIR)

• This is only used with Fourier smoothing and this is done automatically to prevent bad smoothing (the smoothed input EIR sometimes does not match the original monthly values when very low monthly EIR values are used)

Heterogeneity and Availability

• Major overhaul of the heterogeneity features
• Add Gamma distribution for availability of humans to mosquitoes in addition to constant (default) and lognormal
• Possibility to use either a coefficient of variation (CV=...) or variance (variance=...)

<availability /> <!-- default -->
<availability distr="gamma" CV="2"/>
<availability distr="lognormal" CV="2"/>
<availability distr="gamma" variance="3"/>
<availability distr="lognormal" CV="3"/>

Deploy interventions based on human availability to mosquitoes (heterogeneity)

Add the possibility to deploy interventions with a minimum and / or maximum host availability. This is only useful when heterogeneity is used. This may be used for example to simulate the deployment of interventions to remote areas where hosts are more exposed to bites.

Heterogeneity in human-to-mosquito availability can be enabled in the vector model by specifying a distribution and coefficient of variation (or variance) for each species. For example: <availability distr="lognormal" CV="2"/> or <availability distr="gamma" variance="2"/>

OpenMalaria will pre-compute percentiles by sampling the distribution made of the sum of the availability distribution for each species. Only the raw availability will be considered here, this excludes reduction in availability due to age or interventions.

The deployment of human interventions (timed, cumulative or continuous) now allows a minimum and / or a maximum availability percentile, as follows:

    <interventions name="GVI example">
        <human>
            <component id="GVI_example">
                <GVI>
                    <decay function="exponential" L="3y"/>
                    <anophelesParams mosquito="gambiae_ss">
                        <deterrency value="0.7696"/>
                        <postprandialKillingEffect value="0.0544"/>
                    </anophelesParams>
                    <anophelesParams mosquito="funestus">
                        <deterrency value="0.7696"/>
                        <postprandialKillingEffect value="0.0544"/>
                    </anophelesParams>
                    <anophelesParams mosquito="arabiensis">
                        <deterrency value="0.7696"/>
                        <postprandialKillingEffect value="0.0544"/>
                    </anophelesParams>
                </GVI>
            </component>

            <deployment name="GVI_example">
                <component id="GVI_example"/>
               <timed>
                    <deploy coverage="0.8" maxAge="95" minAge="0" minAvailability="50" maxAvailability="100" time="2005-01-01"/> 
                </timed>
            </deployment>
        </human>
    </interventions>

Only hosts within the availability percentile range will be considered. If not specified, the range will be 0-100%. Note that 100% is equivalent for infinity.

Advanced decay functions (with heterogeneity)

This is a major overhaul of the decay function implementation. Decay function objects have now entire control on the heterogeneity implementation, which was not the case before. This allows for more complex decay functions to exist.

Decay functions are now stored as unique_ptr. They still need to be sampled via the hetSample method. When doing so, the hetSample method now returns a new (sampled cloned) instance of the decay function, rather than a heterogeneity factor. This allows the decay functions to have their own implementation of heterogeneity, whether it is just sampling and returning a new internal heterogeneity factor or something more complicated depends on the decay function type.

Heterogeneity can be enabled with the CV parameter. Older decay functions sample the half-life of the decay function using a log-normal sampler. Each host then has a different copy of the decay function with a half-life that differs from the mean.

There are four new decay function types: plus, minus, divides and multiplies, as illustrated below.

Example 1. A biphasic function as the sum of two exponential decays. Note that both the plus, minus, divides and multiplies decay functions expect exactly two other decay functions and they will return an error otherwise. In this example, the other decay functions are added together. This decay function is maxed at 1.0. Note that we can give an initiallEfficacy to each decay function to weigh their importance. initialEfficay is 1.0 by default and is only really needed for the plus and minus decay functions, but it can be used for all decay functions.

<decay function="plus">
    <decay function="exponential" L="1y" initialEfficacy="0.5"/>
    <decay function="exponential" L="20y" initialEfficacy="0.5"/>
</decay>

Example 2. Using s step function to abruptly stop the decay. Here the exponential decay will suddenly stop after 2 years.

<effect function="multiplies">
    <decay function="exponential" L="5y" />
    <decay function="step" L="2y" />
</effect>

Example 3. Recursive definitions are allowed.

<decay function="multiplies">
    <decay function="plus">
        <decay function="exponential" L="1y" initialEfficacy="0.5"/>
        <decay function="exponential" L="20y" initialEfficacy="0.5"/>
    </decay>
    <decay function="step" L="25y" initialEfficacy="1.0"/>
</decay>

Example 4. Biphasic with heterogeneity.

<decay function="plus">
    <decay function="exponential" L="5y" initialEfficacy="1.0" CV="2"/>
    <decay function="exponential" L="10y" initialEfficacy="0.0" CV="2"/>
</decay>

In addition, the parameter used to make a decay function increase has been renamed from complement to increasing.

Other updates

• Code refactor of parts the code
• Cleanup doc folder
• New docker files
• New test scenarios
• Update example scenario
• Fix BetaSampler when variance is > 0
• Throw exception if the seekingDeathRate is negative
• Improve the performance of the DescriptiveWithinHost model

Schema 45.0 release

Deprecation warnings are now displayed by default (PR#359)

• The --deprecation-warnings command-line option has been removed
• A new --no-deprecation-warnings command line option has been added to hide the warnings

Add new and updated example scenario (PR#360)

Replace the old example_scenario.xml file by a new and updated one. The new scenario does not contain any obsolete parameters and is commented with tips and appropriate links to the wiki.

The new scenario also comes with an updated plot.py file that is able to put together some simple plots based on the example_scenario.

Add new nodes to Clinical Model Decision Tree (PR#362)

This is a major update of the DecisionTree module of OpenMalaria. This DecisionTree can be used in the more flexible DecisionTree5Day healthsystem, which replaces the ImmediateOutcomes healthsystem module.

This update adds two nodes to the DecisionTree and the possibility of reporting events to surveys, which can used to more accurately model specific scenarios.

The <fever> node

Similarly to the <diagnostic> node, this one has two possible outcomes <positive></positive> and <negative></negative>. Note that a lookBack parameter must be provided. Any fever that have occurred in the last lookBack days will be counted. Note that this parameter must be less than or equal to the health system memory (hsmemory) parameter. In general, this parameter should be less than or equal to the repeatStep parameter if used in a continuous intervention. As such is only positive if the time of the last event is within both the health system memory and the lookBack parameters for a given host.

Example of a mass test and treat intervention (MSAT) that will treat every symptomatic hosts during one year.

    <component id="MSAT">
      <decisionTree>
          <!-- fevers (counted with healthsystem memory) -->
          <fever lookBack="5d">
            <positive>
              <treatSimple durationLiver="0" durationBlood="1t"/>
            </positive>
            <negative>
              <noTreatment/>
            </negative>
          </fever>
      </decisionTree>
    </component>
    <deployment>
      <component id="MSAT"/>
      <timed>
        <deploy coverage="1.0" time="1992-06-30" repeatStep="5d" repeatEnd="1993-06-30"/>
      </timed>
    </deployment>

The <report> node

This one allows the user to report custom events in the DecisionTree through the healthsystem, interventions, or both. The new measure is available by declaring the following survey option:

<option name="nCMDTReport" outputNumber="90" value="true" byAge="true"/> <!-- nHostsVisited -->

Example of an intervention that will report clinical cases only if the host has fever and tests positive to the RDT diagnostic.

<component id="MSAT">
      <decisionTree>
        <fever lookBack="5d">
          <positive>
              <diagnostic diagnostic="RDT">
                <positive>
                  <report outputNumber="90"/>
                </positive>
                <negative>
                  <noTreatment/>
                </negative>
              </diagnostic>
          </positive>
          <negative>
            <noTreatment/>
          </negative>
        </fever>
      </decisionTree>
    </component>
    <deployment>
      <component id="MSAT"/>
      <timed>
        <deploy coverage="1.0" time="1992-06-30" repeatStep="5d" repeatEnd="1993-06-30"/>
      </timed>
    </deployment>
  </human>

Note that the report node has an additional parameter: outputNumber="X" where X must be an integer. By default, the "nCMDTReport" corresponds to the output number 80. However, it is possible (like with other measures), to declare it multiple times with different outputNumbers. This can be useful to track different categories (by age groups, by cohort, ...), but here we can also use this feature to control the reporting from the <report> node by specifying the output number directly (see example below).

Note that Any positive integer can be used as the outputNumber, but the user will get an error if a measure with the same number has already been declared in the SurveyOptions. If the outputNumber parameter specified in the <report> node does not exist, there will be no error and the report will have no effect. For this reason, it is important to double check that the outputNumbers declared in the SurveyOptions match the outputNumbers declared with <report>.

In addition, note that this will only work for the nCMDTReport measure. If an outputNumber corresponding to another measure is used in <report>, this will have no effect.

Example of an intervention that will report both fevers and clinical cases via the new "nCMDTReport" measure. The number of fever will be reported on measure 80 and the number of clinical cases will be reported on measure 81.

SurveyOptions:

        <option name="nCMDTReport" value="true" outputNumber="80"/> <!-- n fevers -->
        <option name="nCMDTReport" value="true" outputNumber="81"/> <!-- n clinical cases -->

Intervention:

   <human>
    <component id="MSAT">
      <decisionTree>
        <multiple>

          <!-- fevers (counted with healthsystem memory) -->
          <fever lookBack="5d">
            <positive>
              <report outputNumber="80"/>
            </positive>
            <negative>
              <noTreatment/>
            </negative>
          </fever>

          <!-- clinical incidence (counted with healthsystem memory) -->
          <fever lookBack="5d">
            <positive>
              <diagnostic diagnostic="RDT">
                <positive>
                  <report outputNumber="81"/>
                </positive>
                <negative>
                  <noTreatment/>
                </negative>
              </diagnostic>
            </positive>
            <negative>
              <noTreatment/>
            </negative>
          </fever>

        </multiple>
      </decisionTree>
    </component>
    <deployment>
      <component id="MSAT"/>
      <timed>
        <deploy coverage="1.0" time="1992-06-30" repeatStep="5d" repeatEnd="1993-06-30"/>
      </timed>
    </deployment>
  </human>

Another example where the DecisionTree is used to compute nPatent and nUncomp.

SurveyOptions:

      <option name="nCMDTReport" outputNumber="3" value="true" byAge="true"/> <!-- replaces npatent -->
      <option name="nCMDTReport" outputNumber="14" value="true" byAge="true"/> <!-- replaces nUncomp -->
      <option name="nCMDTReport" outputNumber="80" value="true" byAge="true"/> <!-- nHostsVisited -->

Intervention:

<component id="MSAT">
          <decisionTree>
              <multiple>

                  <report outputNumber="80"/> <!-- nVisited -->

                  <diagnostic diagnostic="standard">
                      <positive>
                          <report outputNumber="3"/> <!-- replaces nPatent -->
                      </positive>
                      <negative>
                          <noTreatment/>
                      </negative>
                  </diagnostic>

                  <fever lookBack="5d">
                      <positive>
                          <multiple>
                              <treatSimple durationLiver="0" durationBlood="1t"/>
                              <report outputNumber="14"/> <!-- replaces nUncomp -->
                          </multiple>
                      </positive>
                      <negative>
                          <noTreatment/>
                      </negative>
                  </fever>

              </multiple>
          </decisionTree>
      </component>

      <deployment>
        <component id="MSAT"/>
        <timed>
          <deploy coverage="1.0" time="1993-06-30" repeatStep="5d" repeatEnd="1994-06-30"/>
        </timed>
      </deployment>

Add increasing decay functions with complement=true option (PR#356)

Add a complement parameter to DecayFunction, which makes the decay function return 1-f(x) instead. Since DecayFunctions assume 0 <= f(x) <= 1.0, this produces an increasing effect where the function will "decay" to 1.0 instead of 0.0.

Add ProbDeathSeeking to VectorPop intervention (PR#353)

Add probDeathSeeking parameter effect to the VectorPop intervention. This parameter must be specified as a decay function and allows the user to set the probability of dying while host seeking.

It can be used as follows:

<probDeathSeeking initial="0.01">
        <decay L="3" function="step"/>
</probDeathSeeking>

When using this effect, OpenMalaria will dynamically compute the corresponding increase in death rate while host seeking (mu_vA). This is done by internally solving an equation numerically every timestep, and as such a small drop in performance must be expected.

If multiple VectorPop interventions overlap, the cumulative probability will be used. Note that it cannot exceed 1, and OpenMalaria will return an error during the simulation if it ever happens.

Add new severe measures excluding comorbidities (PR#351)

Add two new measures:

• nSevereWithoutComorbidities (81)
• expectedSevereWithoutComborbidities (82)

which are the same as 'nSevere' and 'expectedSevere', respectively, but without counting cases caused by comorbidities.

Note that 'nSevere' and 'expectedSevere' are unchanged.

Fix heterogenity of availability not working and add the option of using daily values with forced EIR in the Vector Model (PR#354)

• Fix heterogenity of availability not working correctly with the Vector Model
  • The Vector Model now uses the intervention availability instead of the initial availability
• Add the option of using daily values in the vector model
  • Only works with forced EIR
• Add the option of using the changeEIR intervention with the Vector Model
  • Only works with forced EIR
  • Only works with one species

This update also affects the way EIR is computed in the model. Previously, Fourier coefficients were calculated and stored inside the AnophelesModel where they were used to compute EIR values at the time-step level. Scaling the EIR meant scaling the Fourier coefficients. With this update, Fourier coefficients are only used during initialization to calculate EIR values at the time-step level and are no longer used in the AnophelesModel. The AnophelesModel now relies on a vector of EIR values at the time-step level and it has become agnostic of what method is used to calculate the EIR values. Scaling the EIR means scaling the vector of EIR values at the time-step level.

Fourier coefficients are only used when:

• Monthly values are used with the smoothing="fourier" option during initialization
• Fitting the simulated EIR to the input EIR after the warmup period with mode="dynamic"
• Initializing EIR values directly from Fourier coefficients

This also makes it possible to use daily values directly without smoothing and without Fourier coefficients with the Vector Model. For the same reasons, it is also possible to use the changeEIR intervention, right now limited to one species and forced EIR.

fix CFR_PF_USE_HOSPITAL ModelOption not working (PR#358)

The CFR_PF_USE_HOSPITAL ModelOption was not assigned a value during initialization and was consequently always false, even if declared true in the xml. No errors were reported. This fixes the issue.

Add two test scenarios (PR#362)

• test/scenarioDecisionTree5DayDielmo.xml to test the updated DecisonTree5Day module
• test/scenarioHetVecDailyEIR.xml to test daily values and heterogenity in the Vector Model

Fix error when totalDensity is 0 in sumlogDens survey (PR#342)

If the diagnostic specificity is less than 1.0, then there will be false positives, which is expected. However, OpenMalaria will try to report the sum of the log of the totalDensity values for each host, even when "sumlogDens" is false in the survey optons. Computing log(totalDensity) when totalDensity is 0 is not valid and raises an errno error, which is then reported in the main(). With this commit, OM will not compute the log if totalDensity is 0.

Fix error when mean is 0 in LogNormalSampler (PR#358)

During the initialization of the LogNormalSampler, mu is set as log(mean), which will raise an error when the mean is 0. This commit sets mu to -infinity directly when mean is 0, without computing the log first.

Github Actions workflow updates

• Update the the action checkout to version 3 to avoid a warning (PR#344)
• Remove Ubuntu 18.04 as it is now obsolete (PR#344)
• Add macos 12 ubuntu 22.04, Remove macos 10.15 (PR#350)

Continous integration with Appveyor for Windows updates

Note: cmake is broken in Cygwin: https://github.com/appveyor/ci/issues/3508 and cannot be updated without also upgrading the entire cygwin distribution

• Force a Cygwin upgrade and fresh cmake install from the official package list (PR#357)
• Fix error in Appveyor builds due to a change of permissions (PR#348)

Schema 44.0 release

• Fix --verbose not working (PR#338)
• Add the possibility to specify per genotype vaccine efficacy for all the three vaccines implemented in OpenMalaria: PEV, TBV and BSV. (PR#339)

The VACCINE_GENOTYPE model option must be set:

        <ModelOptions>
            <option name="VACCINE_GENOTYPE" value="true"/>
        </ModelOptions>

When the VACCINE_GENOTYPE option is set, the user MUST provide a phenotype description including initialEfficay values for each locus and allele defined in the parasiteGenetics section of the xml.

...
<PEV> <!--assuming csp (from RTS.S-A01), anti-circumsporozoit -->
        <decay L="7.32" k="0.69" function="weibull"/>
        <efficacyB value="10.0"/>   <!-- efficacyB is used in beta distribution to assign efficacy of vaccine to an individual, allows heterogeneity-->
        <phenotype name="sensitive">
                <restriction onLocus="x" toAllele="sensitive"/>
                <initialEfficacy value="0.91"/>
                <initialEfficacy value="0.49"/>
        </phenotype>
        <phenotype name="resistant">
                <restriction onLocus="x" toAllele="resistant"/>
                <initialEfficacy value="0.91"/>
                <initialEfficacy value="0.49"/>
        </phenotype>
</PEV>
...
<parasiteGenetics samplingMode="tracking">
        <!-- Define name/freq/fitness of the locus/alleles defined in the drugPD code -->
        <locus name="x">
                <allele fitness="1" initialFrequency="0.5" name="sensitive"/>
                <allele fitness="1" initialFrequency="0.5" name="resistant"/>
        </locus>
</parasiteGenetics>
...

When VACCINE_GENOTYPE is set, nExpected is no longer affected by the PEV vaccine. Only the reporting is affected, and the simulation will work as expected.

Schema 43.1 release (see: PR#313)

• Update the schema documentation for propActive (behaviour is unchanged from version 43.0)
• Remove the boost dependency, OpenMalaria is a lot easier to compile yourself now
• Add Docker image files for versions 30.3, 35.0, 36.0, 38.0, 40.0, 41.0, 41.1, 42.0 and 43.0 under docker/
• Fix two errors related to "Numerical result out of range" error
• Add an errno check every loop to make it easier to spot similar errors
• Transition from Travis to Github actions for continuous integration Ubuntu and MacOS (tests and releases)
• Start refactoring some parts of the code
• Add a rudimentary verbose output

Schema 43 release

• Add non-human hosts interventions #290
• propActive can be used again but it can only be set to either 0 or 1 #290
• Probabilities PAh, PAmu and PA1 have been added to the continuous output #290

output	versions	description
P_Amu	from 43.0	The probability that a mosquito dies on a given night
P_A1	from 43.0	The probability that a mosquito finds a human host on a given night
P_Ah	from 43.0	The probability that a mosquito finds a non-human host on a given night

Schema 42 release

• Improve the fitting of the emergence rate, which results in a more accurate simulated EIR #281
• Replaced the RNG with ChaCha #284
• Disable propActive by setting it to 1 #280
• New build script 'build.sh' used with automated builds with Travis and Appveyor #260 #265 #268 #271
• Windows releases are compiled with Cygwin, which is more consistent with the Linux builds. All dependencies are provided via Cywgin packages #261. The release is standalone.
• A checkpoint file path/name can be specified #263

Schema 41.1 release

• Fix a bug that prevented scaling of the emergence rate during the fitting phase #269

Schema 41 release

Downloads

• Enable modeling of HRP2 deletions: #248
• Switch to PCG random number generator: #242
• Update Python scripts to Python 3.x: #245
• Automatic build of schema docs: #239
• More adjustments to build scripts: #240, #241, #243, #244
• Code quality improvements: #246, #247

Schema 40 release

Version 40.3

• Add innoculationsPerVector output: #238

Version 40.2

• Adjustments to random number generation support code: #235
• Add --compress-output option; remove BOINC code: #236
• Misc. fixes to build and code documentation: #237

Version 40.1

• Fix numerical integration used in PK/PD model: #234

Version 40.0

This version includes breaking changes to the XML schema; see schema update guide.

• Adjustments to 3-compartment PK/PD model: #227
• Code improvements enabled by C++11: #228
• PK/PD conversion model: allow covariance of IC50 samples #229
• Consistent specification of log-normal samples: #230

Schema 39 release

Versions 39.1.1 - 39.1.4

• Guard against log(0) from monitoring system: #216
• Tweak automated builds: #217, #218, #221, #222, #223

Version 39.1

• #215: Allow IC50 to be sampled per infection

Version 39.0

• #212: Update version number
• #211: Bug fix: pass correct value for age and handle delay
• #208: Update to C++11
• #202: Fix reading the checkpoint time as a command line option
• #199: Name cleanup

Schema 38 release

Pull request

• Add mosquito fecundity modifier for non-human hosts
• Allow human-vector interventions to affect mosquito fecundity

Version 38 code — released Oct 2017.

Schema 37 release

Pull request

• Add "logit" parameterisation for ITNs
• Fix for genotype sampling given zero transmission (imported cases?).
• Some schema documentation improvements
• SimTime.h became sim.h
• Human population and transmission class objects became directly-accessible globals to save passing
• Non-human-host fix (no effect on output, assuming number of NHHs was 1 for each type)
• Some work to limit uses of human population in transmission code to small regions
• ?

Version 37 code — released Jan 2017.

Schema version 36

Version 36.1.1 release

Bugfix release for example scenario, example_scenario.xml now uses schema_36. This new version introduces testing for the example_scenario.xml we distribute each release.

Version 36.1 release

Version 36.1 code — released April 2016.

This fixes bugs #134, #155 and #169.

In particular, the PK & PD convergence models have been fixed to generate the correct values for Artemether-DHA and Artesunate-DHA drugs (at least, the values from both models now match those produced from an independent implementation in R).

There are no changes to the XML / XSD in this release (except that PK/PD parameters for these models are now included in the snippet library).

Version 36.0 release

Version 36 code — released April 2016.

Revised monitoring code (equivalent functionality). Updated doc of existing functionality.

onlyNewEpisode monitoring option replaces REPORT_ONLY_AT_RISK model option. Both affect many measures simultaneously.

Vector traps intervention.

Schema version 35

Schema 35 code — released February 2016.

Expected deaths / severe cases

The goal of this change is to allow simulations to be run with smaller population sizes while still getting useful data on rare events (deaths, severe cases and sequelae). Extra outputs allow the expected number of cases to be calculated. Formulae for doing this have not yet been derived or experimentally proved. See ticket 151.

Documentation of monitoring measures

Triggered interventions

Triggered interventions allow deployments to be enabled (or disabled) by specific conditions. Documentation. Related features:

• Conditions of deployment
• Unreported surveys
• Regular deployments (link; see down a few paragraphs)

Schema version 34

Schema 34 code — released September 2015.

For details about related work packages have a look at milestone Schema-34.

Schema changes requiring updates to scenario XMLs

Pharmacokinetics (PK):

<medicate>:

• Removed <duration> (link to schema-33 doc) attribute for IV administration. Code regarding intravenous drug administration has been removed as well.

Vivax:

• <hypnozoiteReleaseDelayDays> has been renamed to <hypnozoiteRelease> and has a new structure, which has an option to specify multiple release distributions of liverstage parasites (for simulation of delayed hypnozoite-releases).
• <primaquine> has been renamed to <liverStageDrug>
• Monitoring option nPQTreatments has been renamed to nLiverStageTreatments

Backwards-compatible schema changes

New PK models:

• Drug Three compartment model
  • uses absorption rates for compartments 2 and 3:
    • <compartment2>, <a12>, <a21>
    • <compartment3>, <a13>, <a31>
    • Absorption rate constant (<k_a>)
• Drug conversion model (experimental)
  • Conversion parameters
    • <metabolite>: Metabolite drug (abbreviation)
    • <rate>: Rate of conversion
    • <molRatio>: Molecular weight ratio
    • Details: see #53 and #134. Will be patched in a follow up release of schema-34 (see Schema-34.1 Milestone)_

PKPD:

Dosages:

• New <multiply> child element for <dosages> which multiplies the dose <by> some quantity - such as patient weight.
• New drug decay constants (as alternative to drug half-life):
  • elimination rate (<k> & <m_exponent>)

Intervention usage #56:

• <GVI> and <IRS> now have an optional <usage> element.
• <ITN>'s <usage> child element is now optional too.

It is assumed that when no <usage> element is given the usage modifier is 1 (100%) (proportion of use for a given intervention which modifies the protectional effect).

Schema version 33.1

Schema 33.1 code — released July 2015

Includes new semantic versioning: Schema-33.1

Schema version 33

Schema 33 code — released December 2014

supplementary changelog

Schema changes requiring updates to scenario XMLs

Mass drug deployment interventions (MDA/MSAT/T&T)

The "MDA1D" component has been replaced with "decisionTree", a component which runs a case management decision tree on deployment; this is now usable with 5-day timestep models and gives a flexible way to implement T&T or similar campaigns.

The "MDA" component has been replaced with "screen", "treatSimple" and "treatPKPD" components. The first of these uses a diagnostic and optionally triggers deployment of one or more other components on positive and/or negative outcomes while the latter offer two ways of treating infections.

Backwards-compatible schema changes

Some of these changes offer additional functionality and some are recommended but optional changes to enhance clarity of the XML or improve models. Running OpenMalaria with the --deprecation-warnings option will print messages recommending possible changes in XML documents.

Time units (improved clarity):

Previously dates and durations were given in days, time steps or years with only a little documentation to indicate which unit should be used. Now most of these inputs accept units of days, steps or years with an explicit unit, and in the case of absolute times (i.e. not durations), dates.

Diagnostics (bug fixes, new capabilities):

Previously the diagnostic used for monitoring purposes was deterministic with a specified detection limit, interpreted as being derived from either Garki or common (non-Garki) microscopy methods, while diagnostics used by the health system and intervention deployment could be either stochastic or deterministic with configurable limits but did not adjust these for the density estimation method (bug). Now all diagnostics can be specified with Garki, common or Malaria-therapy detection limits as deterministic or stochastic tests. Further, the diagnostic used by the neonatal mortality model may be independant of that used in monitoring.

Parasite genetics (new model):

A new model has been introduced for selecting parasite genetics, with specification of initial genotype frequency and fitness, and (vector transmission model only) optional tracking of genotype frequency.

This replaces the simplistic genotype model previously embedded within the PK/PD model and allows modeling the spread of drug resistance in OpenMalaria.

Monitoring (more options, some non-backwards-compatible changes):

Much of the monitoring code was rewritten to be easier to extend. XML configuration and output files remain backwards compatible but with new options: output identifier is configurable, measures can be configured to aggregate over some dimensions (age group, cohort, species, genotype) to reduce output size, new measures (for tracking parasite genetics) are available.

Vector species was previously indicated via name in output files but is now numeric.

Some measures have been disabled (which?).

Health system (clarity, new capabilities):

A new health system model is available (essentially a merge of the old ImmediateOutcomes and unused EventScheduler) models. This specifies access and severe outcomes as the ImmediateOutcomes model but uses decision trees to describe uncomplicated treatment. As with the ImmediateOutcomes model, this is only functional on a 5-day timestep.

Molineaux infection model (bug fixes):

The Molineaux infection model has been improved slightly. Most notably, blood volume is derived from human age (giving infants lower volume and higher parasite density elimination thresholds), and parameter sampling for new infections has been fixed (non-pairwise-sampling mode).

New testing code has also been written for the model.

Tool changes

The plotResults.py script was updated to handle new outputs and allow plotting results by cohort and genotype (on x-axis as separate lines).

Schema version 32

Schema-32 code - released 24th June 2014

supplementary changelog

• Many changes to human-targeting intervention descriptions as well as a few changes elsewhere in the XML
• Human-targeting interventions can have multiple descriptions and be deployed simultaneously with other human-targeting interventions
• Sub-populations replace "cohort" for intervention deployment purposes
• Sub-population removal replaces cohort on-first-event and cumulative intervention deployment's age; resetting of health-system memory works slightly differently
• Monitoring of multiple cohorts (derived from sub-populations)
• More generic vector interventions targeting humans: the new Generic Vector Intervention (GVI) model replaces the old vector deterrent and IRS v1, what was IRS v2 is now just IRS
• New non-PK/PD treatment model for 5-day timestep health system and for MDA/MSAT. Allows delayed treatment, treating only liver and only blood stages, and prophylactic effects.
• Case management can use diagnostics before treating patients
• Case management can trigger deployment of any intervention
• New 'screen' intervention component which uses a diagnostic, then deploys interventions from a list depending on outcome (replaces MDA's diagnostic)
• Removed the IPT model (the treatment model mentioned above allows a prophylactic effect which was the main thing IPT code was still used for; there is however no current replacement for modelling resistant infections which IPT code had a very basic model for).
• Vaccines: vaccine effects (PEV, BSV, TBV) are now described independently
• Vaccine schedules: removed the implicit schedules used previously by all age-based deployments and added explicit schedules
• Bugfix: treat and apply indirect mortality correctly (this is an option, enabled by default).
• The R_0 special intervention has been disabled (purely to avoid maintenance work; it can be re-enabled if needed)
• New output/monitoring measures (56 - 60)
• Removed some "continuous" monitoring measures
• Included simple P. vivax model (originally developed on top of version 31)
• Explicit namespace in XML: scenario → om:scenario and XML header changes
• Clarified the order in which intervention effects are deployed, making sure that cohort selection happens first.
• Reorganise intervention code: most now lives in the interventions folder and namesake namespace; details commonly needed elsewhere in the code now live in Interfaces.hpp.
• Reorganise XML loading code: what was in inputData.h/cpp has moved to Parameters.h/.cpp and util::DocumentLoader.h/.cpp
• Partial implementation of a Vivax model (which would be used instead of any Falciparum infection models in the simulator). Not yet usable but motivated some code changes: the old WithinHostModel class has been replaced by WHInterface and WHFalciparum and the Pathogenesis, Diagnostic and (new, non-PK/PD) Treatments models have moved within the WithinHost namespace/directory.
• An anonymous conservation society decided that elimination of P. falciparum isn't always desirable. Some other changes to tests.

Updating scenarios from schema 31:

• Any human-targeting interventions need to be updated to the new syntax
• The health system needs a description of treatment actions (5-day timestep)

There is a tool to do this in an automated fashion. Note that the tool will ask what behaviour to use for health system treatment actions, but just not MDA treatment actions. You may want to review these after the update.

Schema Version 31

Released 8th July 2013

• Simple mosquito population dynamics model: model allowing reduced numbers of adult mosquitoes to reduce the numbers of eggs laid.
• Enabled INNATE_MAX_DENS by default
• Included seekingDeathRateIncrease and probDeathOvipositing interventions
• Allow multiple descriptions of the larviciding intervention as well as the new interventions
• ITN and IRS tweaks
• New mod and mod_nn functions to avoid undefined behaviour of x%y
• Lots of bug fixes and code maintenance

Schema Version 30.4

Parallel development in July 2013 to add new models to the fitting runs

• Make the sigma parameter of the Penny infection model fittable
• PENNY_JULY_2013 variant of the Penny 1-day-timestep model

Schema Version 30 - 30.3

Released 12th April 2012 as r2258

• Renamed Vector_EIR_Input and Vector_EIR_Simulated to inputEIR and simulatedEIR respectively.
• Increased delay in human infectiousness model from the perspective of the non-vector model and several summaries: it appears it was one time-step short.
• Bug fix in REPORT_ONLY_AT_RISK: after a case at time 0, times 2-5 were considered not-at-risk. This corrects those timesteps to 1-4.
• mode parameter of <entomology> element now takes keyword value: dynamic or forced.
• Vector model XML parameters now largely use elements instead of being one long string of attributes.
• Vector parameters α_i, P_B_i, P_C_i and P_D_i (rate of encountering hosts and probabilities of biting, escaping and resting respectively) may now vary across humans to simulate human heterogeneity.
• NC has extended the vector model with simulation of the egg, larval and pupal life-stages.
• A larviciding using the vector life-cycle model will be included.
• Vector-model inputs will be changed: transmission input will be in the form of a seasonality profile and IBPAPA (infectious bites per adult per annum), where the seasonality profile can be that of transmission (as before) or that of vector densities. Fitting of internal parameters to reproduce this seasonality should be better than before (in progress).
• SchemaTranslator is now compiled by cmake (output is build/util/SchemaTranslator/SchemaTranslator.jar)
• Seasonality parameterisation of per-vector transmission is now input differently to allow other data sources to be used as seasonality inputs in the future.
• Added an output: nMassScreenings (number of diagnostics used by MSAT, or number of recipients of MDA if no diagnostic is used)
• New IRS model & parameterisation (to be documented)
• Old IRS model can also have a preprandial effect
• Heterogeneity of decay in the ITN model has been made per-human rather than per net (mistake in previous release)
• New continuous output options

Schema Version 29

Released on 21st June as r1902.

• New ITN model
• MSAT for 5-day timestep.

Schema Version 28

Released on 24th May 2011 as r1836.

Big rearrangements of interventions content, moving from grouping by description and deployment type to grouping by intervention. This should make experiment design easier. Each intervention can optionally have a name attribute.

Changed some names:

• drugDescription -> pharmacology
• entoData -> entomology
• eir -> EIR
• monthlyEir -> monthlyEIR

Added optional name attributes to intervention descriptions.

New implementation of imported infections "intervention".

Larviciding intervention removed; it will be replaced by a more accurate model later.

Schema Version 27

Released on 6th May 2011 as r1811.

• Fix for Penny's infection model (code)
• There should no longer be NaNs in output files when the model runs successfully
• new continuous reporting option: median immunity Y
• descriptions of vector interventions are no longer required in cases where the intervention is never deployed
• bug fix: initialize microscopy count
• made transmission warm-up fitting problems interrupt the program again

Schema Version 26

Released on 23rd February 2011 as r1704.

• Transmission model's initialization strategies updated.
• Simulated EIR outputs changed to only be outputs from adults.
• Implementation of Penny infection model and unittest against Matlab densities.
• Decay functions updated with "step" function and optional heterogeneity.
• 1-day time-step case-management: treatment-seeking delays for UC cases has new description.
• Non-malaria morbidity: separate P(need antibiotic treatment) for fevers classified as malarial.

Schema Version 25

Released on 24th Janruary 2011 as r1622.

• Non-malaria fever modelling implemented
• Cumulative intervention deployment: bring coverage up to a target level
• MDA intervention may now be configured as "screen & treat" (1-day time-step)
• Some IV-drug corrections and (hopefullly) a speed-up
• Decay of vector-stage interventions and vaccines can now be modelled using several different functions
• Vaccine codes are now PEV/BSV/TBV instead of 1/2/3
• Deterministic case management trees no longer make an unnecessary random-number generator call
• Time-steps encapsulated in a new class for added type-saftey

Schema Version 24

Released on 27th December 2010 as r1578.

• units of EIR input changed to be adult-averaged in all cases
• vector fitting revision: use a single 5-year period
• drug code for intravenous administration of drugs (where duration of administration is significant)
• proposed cohort implementation completed: options for removal and all outputs restricted to cohorts
• generic handling of data per age-group and interpolation methods
• heterogeneity in human weight included

Schema Version 23

Released on November 4th 2010 as r1420, tagged openmalaria-649.