ModelDecayFunctions

Decay functions

Several interventions, such as bed nets and vaccines, have an effectiveness which decays over time (at the population and possibly the individual level). To allow use of different decay functions, a generalized method of describing decay was added into schema version 25. The following set of functions are available:

function	formula	L is time to
constant	1		no decay, ever
step	1	full decay	for t >= L, otherwise 0
linear	1 - t/L	full decay	for t < L, otherwise 0
exponential	exp( - t/L * log(2) )	half decay
weibull	exp( -(t/L)^k * log(2) )	half decay	equivalent to exponential when k = 1
hill	1 / (1 + (t/L)^k)	half decay
smooth-compact	exp(k - k / (1 - (t/L)^2))	full decay	for t < L, otherwise 0

where L is a description of the rate of decay, either the time until half decay or the time until full decay (see above) in years, and k is a shape parameter (no dimension).

The smooth-compact, step, and linear decay functions reach zero at time L, whereas the Weibull, Hill and exponential functions never reach zero and have half their original efficacies at time L.

Configuration

For certain interventions, the decay of efficacy is described by an XML element of type DecayFunction. A few examples follow:

<eltName L="10.0" function="exponential"/>
<eltName L="3d" function="weibull" k="1.5"/>
<eltName L="3d" function="weibull" k="1.5" CV="0.1"/>

The function, L and k attributes act as described above, with k optional (defaults to 1 if not specified). Note: L must be specified even when function="constant", but is ignored in this case (so stick in any value to make OpenMalaria happy).

Heterogeneity

Starting with version 26 of OpenMalaria, variations can be introduced into decay rate: a random variate x is sampled from the log-normal distribution, and t in the above formulas is replaced by t/x.

As of version 40, one simply specifies the attribute CV="...". (The mean of the log-normal sample is fixed to 1.)

Prior to version 40, the attributes mu and sigma must be specified. Both take value 0 if not specified (arguably a bug, so be sure to specify mu if using heterogeneity). If sigma this is non-zero, x is sampled from the log-normal: x ~ lnN(mu,sigma²).

If these attributes are not specified, there will be no heterogeneity (effectively x=1).

Advanced decay functions

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.

Version 46 brings 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>