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.

The following model option can be enabled to use the new emergence rate calculation method.

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

Note that this option is set to "false" by default, and OpenMalaria will fallback to the same iterative method that has been used in previous versions to estimate the emergence rate.

Using this new method, OpenMalaria will calculate the emergence rate by solving the equations described here using a fast root-finding algorithm. This method is faster, but also helps getting a more accurate SimulatedEIR (closer to the InputEIR), especially for low annual EIR inputs (<5).

However, it is possible that this method produces negative emergence rate values, which will result in the following explicit error:

Error: The exact emergence solver produced negative emergence rates. With the current mosquito mortality/survival parameters, the requested EIR likely falls faster than the infectious mosquito population can decline biologically; matching it exactly would require negative emergence. Recommended action: smooth the EIR seasonality. Alternatively, remove <option name="USE_EXACT_NV0_SOLVER" value="true"/> to use the legacy adaptive fitter. This may allow the simulation to run, but the simulated EIR may deviate more from the input EIR.

See: https://github.com/OpenMalaria-Org/openmalaria/wiki/ScenarioTransmission#exact-emergence-rate-calculation-from-version-49-onwards

OpenMalaria now distinguishes a missing/misplaced/misnamed XSD file from a non-conforming scenario. The former now gives the concise message below instead of 100+ lines of errors. A non-conforming scenario still produces the detailed validation output.

Parsing scenario file failed.
        Likely the XSD schema file is not present at an expected location/with expected filename.
OpenMalaria: No such file or directory

We have added support for the ARM64 architecture. We have added a new workflow to build a multi-arch Docker image compatible with AMD64 and ARM64 architectures: https://hub.docker.com/r/swisstph/openmalaria/tags.

minInfectedThreshold is the number of mosquitoes below which transmission is interrupted. This used to be an arbitrary threshold, which can cause unexpected elimination in some scenarios. This threshold is now set to 0 by default and it has been removed from the example_scenario.xml, but can still be changed.

Instead, elimination studies should focus on the number of indigenous cases in the population: https://github.com/SwissTPH/openmalaria/wiki/Elimination

<anopheles mosquito="flavirostris" propInfected="0.078" propInfectious="0.000021">

are initial guess values to estimate the number of mosquitoes in the initial population. The population is later adjusted to match the InputEIR provided by the user. Since these parameters are never used, this PR removes them from the schema. They are hard-coded in the C++ code instead.

• The demography growthRate parameter has been removed, since it was not usable anyway
• Code upgrade to C++20

Support named models (#419)

Add a default time step duration to the base model(#422)

• The iseed attribute has been removed from the <parameters> element in OpenMalaria's XML schema. This attribute, being the seed of the random number generator, is not really an attribute of the malaria model itself. It used to be possible to write this.

    <model>
        <ModelOptions>          ...        </ModelOptions>
        <clinical ...>          ...        </clinical>
        <human>                 ...        </human>
        <parameters interval="5" iseed="1" latentp="15d">
                ...        
        </parameters>
   </model>

But now, it is necessary to write the iseed attribute as part of a <computationParameters> element instead (this element is new).

E.g.

    <model>
        <ModelOptions>          ...        </ModelOptions>
        <clinical ...>          ...        </clinical>
        <human>                 ...        </human>
        <computationParameters iseed="1"/> <!-- This is new. -->
        <parameters interval="5" latentp="15d"> <!-- Note the absence of the iseed attribute here. -->
                ...        
        </parameters>
   </model>

The <computationParameters> element must be included even if the <parameters> element is not included.

• Scenarios using the base model can now be written more simply.

Instead of writing model options and parameters for scenarios using the base model calibration like so

    <model>
        <ModelOptions>
            <option name="INNATE_MAX_DENS" value="false"/> <!-- MANDATORY WITH THE BASE MODEL DO NOT REMOVE -->
            <option name="INDIRECT_MORTALITY_FIX" value="false"/> <!-- MANDATORY WITH THE BASE MODEL DO NOT REMOVE -->
            <option name="MAX_DENS_CORRECTION" value="false"/> <!-- MANDATORY WITH THE BASE MODEL DO NOT REMOVE -->
            <option name="HEALTH_SYSTEM_MEMORY_FIX" value="false"/> <!-- MANDATORY WITH THE BASE MODEL DO NOT REMOVE -->
        </ModelOptions>

        ...

        <!-- DO NOT CHANGE THE MODEL PARAMETERS BELOW -->
        <parameters interval="5" iseed="1" latentp="15d">
           <parameter name="'-ln(1-Sinf)'" number="1" value="0.050736"/>
           <parameter name="Estar" number="2" value="0.03247"/>
           <parameter name="Simm" number="3" value="0.138161050830301"/>
           <parameter name="Xstar_p" number="4" value="1514.385853233699891"/>
           <parameter name="gamma_p" number="5" value="2.03692533424484"/>
           <parameter name="sigma2i" number="6" value="10.173598698525799"/>
           <parameter name="CumulativeYstar" number="7" value="35158523.31132510304451"/>
           <parameter name="CumulativeHstar" number="8" value="97.334652723897705"/>
           <parameter name="'-ln(1-alpha_m)'" number="9" value="2.33031045876193"/>
           <parameter name="decay_m" number="10" value="2.53106547375805"/>
           <parameter name="sigma2_0" number="11" value="0.655747311168152"/>
           <parameter name="Xstar_v" number="12" value="0.916181104713054"/>
           <parameter name="Ystar2" number="13" value="6502.26335600001039"/>
           <parameter name="alpha" number="14" value="142601.912520000012591"/>
           <parameter name="Density bias (non Garki)" number="15" value="0.177378570987455"/>
           <parameter name=" sigma2 " number="16" value="1.0"/>
           <parameter name="log oddsr CF community" number="17" value="0.736202"/>
           <parameter name="Indirect risk cofactor" number="18" value="0.018777338"/>
           <parameter name="Non-malaria infant mortality" number="19" value="49.539046599999999"/>
           <parameter name="Density bias (Garki)" number="20" value="4.79610772546704"/>
           <parameter name="Severe Malaria Threshhold" number="21" value="784455.599999999976717"/>
           <parameter name="Immunity Penalty" number="22" value="1"/>
           <parameter name="Immune effector decay" number="23" value="0"/>
           <parameter name="comorbidity intercept" number="24" value="0.0968"/>
           <parameter name="Ystar half life" number="25" value="0.275437402"/>
           <parameter name="Ystar1" number="26" value="0.596539864"/>
           <parameter name="Asexual immunity decay" number="27" value="0"/>
           <parameter name="Ystar0" number="28" value="296.302437899999973"/>
           <parameter name="Idete multiplier" number="29" value="2.797523626"/>
           <parameter name="critical age for comorbidity" number="30" value="0.117383"/>
       </parameters>
    </model>

it is now possible to write the following instead.

    <model>
        <!-- Add this instead! -->
        <ModelName name="base"/>
        ...
        <!-- You can omit <ModelOptions> element. -->
        ...
        <!-- You can omit <parameters> element. -->
    </model>

This makes XML files for scenarios using the base model much more concise and provides an assurance that your scenario is indeed using the base model.

If you want to use most of the base model's setting but override the value of some model options (on/off) or parameters (doubles), this is possible. You can include <ModelName name="base"/> then also include a <ModelOptions> or <parameters> element, as before, and any values written there will override the value of the model option/parameter set by the base model.

If you don't want to use the base model at all, then don't include <ModelName name="base"/> in your scenario.

Currently, no named model other than "base" is supported.

Version 47.0 added support imported, introduced or indigenous infections, see: Wiki: Elimination

In version 48.0, nNewInfections has been added to the list of supported monitoring outputs for Elimination, and can be used to track both _imported, _introduced and _indigenous infections. Note: nNewInfections now includes infections due to imported infections, which was not the case before and could break older simulations (will produce different results) if they were using imported infections.)

In addition, <infectionOrigin> has been to the DecisionTree (#402) with support for <imported>, <introduced> and <indigenous> sub-branches also added. This allows users to apply different treatments or deploy different interventions depending on if the host classifies as imported, introduced or indigenous based on the origin of its current infection(s).

Example of DecisionTree used in an intervention, with a diagnostic:

<component id="MSAT">
  <decisionTree>
    <diagnostic diagnostic="deterministic">
      <positive>
        <infectionOrigin>
            <imported>
                 <treatSimple durationLiver="0" durationBlood="1t"/>
            </imported>
            <introduced>
                 <treatSimple durationLiver="0" durationBlood="1t"/>
            </introduced>
            <indigenous>
                 <treatSimple durationLiver="0" durationBlood="1t"/>
            </indigenous>
        </infectionOrigin>
      </positive>
      <negative>
        <noTreatment/>
      </negative>
    </diagnostic>
  </decisionTree>
</component>

#354, #369, #374, #375, #406.

See: Wiki: Heterogeneous deployment.

Each host receives an availability factor for each Anopheles species in the simulation. In the case where no species are described or if the Vector Model is not used, hosts receive a unique availability factor instead.

The default distribution is set to constant, so that there is no heterogeneity (in terms of host availability to mosquitoes) by default, i.e. all hosts in the simulation receive the same availability factor.

After initialization, the availability of the hosts in the simulation is scaled with a factor proportional to the number of hosts and with respect to other Anopheles parameters.

We used to scale the availability distribution with this factor, which is rather difficult to get right and to maintain. Instead, we now set the mean of the availability distribution to 1 and we scale the sampled host availability with the factor mentioned above outside of the distribution.

The user can introduce a correlation between the availability of a host (drawn for one of the supported distributions for each Anopheles species e.g. LogNormal, Gamma,...) and the coverage probability of the intervention being deployed.

This is done via a Gaussian Copula transformation from one of the available distribution for the host availability to mosquitoes, to a Beta distribution for the coverage probability of the intervention.

Note that this is in fact the latent correlation in the copula transformation and not the direct correlation between availability rate and coverage probability.

This provides three key features:

• Heterogeneous coverage – interventions can now be deployed with realistic variability in coverage across the population.
• Correlation with host availability – individuals more (or less) available to mosquitoes can have systematically higher (or lower) probabilities of receiving the intervention.
• Consistency over time – if a host’s probability of receiving the intervention is high for an initial deployment, it will remain consistently high for subsequent deployments of the same intervention.

Anopheles description (note the availability parameter with a gamma distribution and a CV of 0.5):

<mosq minInfectedThreshold="1">
  <mosqRestDuration value="2"/>
  <extrinsicIncubationPeriod value="12"/>
  <mosqLaidEggsSameDayProportion value="0.59"/>
  <mosqSeekingDuration value="0.33"/>
  <mosqSurvivalFeedingCycleProbability value="0.611"/>
  <availability distr="gamma" CV="0.5"/>
  <mosqProbBiting mean="0.95" variance="0"/>
  <mosqProbFindRestSite mean="0.95" variance="0"/>
  <mosqProbResting mean="0.99" variance="0"/>
  <mosqProbOvipositing value="0.88"/>
  <mosqHumanBloodIndex value=".98"/>
</mosq>

Intervention deployment with a coverage correlation (coverageCorr) of -1 and a coverage variance (coverageVar) of 0.15:

<human>
  <!-- ITN taken from Andrew's optimal allocation project -->
  <component id="kill_repell" name="kill_repell">
    <GVI>
                        <decay L="3" k="1" function="weibull"/>
      <anophelesParams mosquito="funestus" propActive="1">
        <deterrency value="0.44"/>
        <preprandialKillingEffect value="0.27"/>
        <postprandialKillingEffect value="0.27"/>
      </anophelesParams>
    </GVI>
  </component>
  <deployment name="kill_repell_deploy">
    <component id="kill_repell"/>
    <timed>
                        <deploy coverage="0.8" coverageCorr="-1.0" coverageVar="0.15" time="2030-01-01" repeatStep="3y" repeatEnd="2059-01-01" /> 
    </timed>
  </deployment>
</human>

#426 Some code that is deprecated after C++17 was updated.

#425 OpenMalaria was extended to make it easier to add other named models (other than just the "base" model) in future.

#425 The default time step for the base model was explicitly set to 5 days. Before, a 5-day timestep had to be manually specified in the scenario, by the user, in order for the base model to be used.

#424 Add the possibility to truncate samples from the available distributions: LogNormal and Gamma using the truncate="" xml parameter.

#415 Fix checkpointing errors when running non-default heterogeneity and when using the elimnation model.

#412 An unused XML attribute was made unsupported by the OpenMalaria's XML schema.

#411 CI scripts were updated in response to a change in the list of supported OS images for GitHub Actions workflows.

#409 Update example scenario.

#403 Fix small memory leak.

Some updates to documentation were made to improve currency.

This release comes with a new elimination model: see Wiki: Elimination

OpenMalaria supports tracking imported, introduced or indigenous infections. The VectorModel has also been updated to track the population of mosquitoes infected from an imported infection and mosquitoes infected from an introduced or indigenous infection separetly.

Note that these changes have no impact and predictions will be identical to previous versions as long as there is no imported infection. If imported infections are in place then the model will output slightly different results because of an additional rng call in the code.

The expected results of three tests (which use imported infections) had to be updated because of this.

The minimum monthly EIR value is set to 1% of the maximum monthly EIR. This helps conserving the original length of the season better after smoothing (only applicable to when monthly EIR values are used). When low seasonal values (or even zeros) are used, the Fourier smoothing struggles to find a good approximation and the resulting smoothed seasonality may not match the original monthly values well.

The clinical element 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.

Currently in the 5 day model, a value of 6 corresponds to 35 days (not the 30 days previously claimed).

The following model option has been added: HEALTH_SYSTEM_MEMORY_FIX. This option is set to true by default.

The model option <option name="HEALTH_SYSTEM_MEMORY_FIX" value="false"/> must be set to false if used with the current base model.

This makes the health system memory behaves as expected. With this option, specifying a health system memory of 30 days means that a new clinical case will be reported as early as 30 days after the initial case (6 time-steps), rather than 35d (7 time-steps) currently. With this option, setting the health system memory to 5 days allows the model to report a new clinical case every time step.

• Adds <severe> and <cohort component="id"> nodes to the DecisionTree (see: Wiki: DecisionTree).
• example_scenario.xml has been updated
• Adds additional error checks in multiple places

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

Deprecation warnings are now displayed by default (#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 (#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 (#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.

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>

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 (#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 (#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 (#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 (#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 (#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 (#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 (#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 (#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 (#344)
• Remove Ubuntu 18.04 as it is now obsolete (#344)
• Add macos 12 ubuntu 22.04, Remove macos 10.15 (#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 (#357)
• Fix error in Appveyor builds due to a change of permissions (#348)

• Fix --verbose not working (#338)
• Add the possibility to specify per genotype vaccine efficacy for all the three vaccines implemented in OpenMalaria: PEV, TBV and BSV. (#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.

• 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

• 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

• 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

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

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

• Add innoculationsPerVector output: #238

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

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

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

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

• #215: Allow IC50 to be sampled per infection

• #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

#198

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

Version 38 code — released Oct 2017.

#184

• 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.

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 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 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 35 code — released February 2016.

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 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 34 code — released September 2015.

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

<medicate>:

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

• <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

• 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)_

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>)

• <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 33.1 code — released July 2015

Includes new semantic versioning: Schema-33.1

Schema 33 code — released December 2014

supplementary changelog

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.

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.

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.

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.

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.

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?).

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.

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.

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-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.

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

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

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

Released on 21st June as r1902.

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

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.

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

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.

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

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

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