GeneratedVectorTrapsDoc
This page is automatically generated from the following schema file: scenario_current.xsd.
I recommend against editing it because edits will likely be lost later.
Key:
abc required (one)
[ def ] optional (zero or one)
( ghi )* any number (zero or more)
( jkl )+ at least one
( mno ){2,inf} two or more occurrences
→ scenario
<scenario
schemaVersion=int
[ analysisNo=int ]
name=string
[ wuID=int ]
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:om="http://openmalaria.org/schema/scenario__"
xsi:schemaLocation="http://openmalaria.org/schema/scenario__ scenario_current.xsd"
>
IN ANY ORDER:
| <demography ... />
| <monitoring ... />
| <interventions ... />
| <healthSystem ... />
| <entomology ... />
| [ <parasiteGenetics ... /> ]
| [ <pharmacology ... /> ]
| [ <diagnostics ... /> ]
| <model ... />
</scenario>- demography
- monitoring
- interventions
- healthSystem
- entomology
- parasiteGenetics
- pharmacology
- diagnostics
- model
Description of scenario
schemaVersion=intVersion of xml schema. If not equal to the current version an error is thrown. Use SchemaTranslator to update xml files.
analysisNo=intUnits: Number Min: 1 Max: 100000000
Unique identifier of scenario
name=stringName of intervention
wuID=intUnits: Number
Work unit ID. Obselete and no longer required.
→ scenario → demography
<demography
name=string
popSize=int
maximumAgeYrs=double
[ growthRate=double ]
>
IN THIS ORDER:
| <ageGroup ... />
</demography>Description of demography
name=stringName of demography data
popSize=intUnits: Count Min: 1 Max: 100000
Population size
maximumAgeYrs=doubleUnits: Years Min: 0 Max: 100
Maximum age of simulated humans in years
growthRate=doubleUnits: Number Min: 0 Max: 0
Growth rate of human population. (we should be able to implement this with non-zero values)
→ scenario → demography → ageGroup
<ageGroup
lowerbound=double
>
IN THIS ORDER:
| ( <group ... /> )+
</ageGroup>list of age groups included in demography
list of age groups included in demography or surveys
lowerbound=doubleUnits: Years Min: 0 Max: 100
Lower bound of age group
→ scenario → demography → ageGroup → group
<group
poppercent=double
upperbound=double
/>poppercent=doubleUnits: Percentage Min: 0 Max: 100
Percentage of human population in age group
upperbound=doubleUnits: Years Min: 0 Max: 100
Upper bound of age group
→ scenario → monitoring
<monitoring
name=string
[ startDate=string ]
>
IN THIS ORDER:
| [ <continuous ... /> ]
| <SurveyOptions ... />
| <surveys ... />
| <ageGroup ... />
| [ <cohorts ... /> ]
</monitoring>Description of surveys
name=stringName of monitoring settings
startDate=stringAn optional date for the start of monitoring. If given, dates may be used to specify when other events (surveys, intervention deployments) occur; alternately times relative to the start of the intervention period may be used to specify event times.
Setting this to 1st January of some year might simplify usage of dates, and putting the start a couple of years before the start of intervention deployment (along with some extra surveys) may be useful to check transmission stabilises to the expected pre-intervention levels.
As an example, if this date is set to 2000-01-01, then the following event times are equivalent (assuming 1t=5d): 15t, 75d, 0.2y, 2000-03-16.
Must be in the form YYYY-MM-DD, e.g. 2003-01-01.
→ scenario → monitoring → continuous
<continuous
period=string
[ duringInit=boolean ]
>
IN THIS ORDER:
| ( <option ... /> )*
</continuous>period=stringUnits: User defined (default: steps)
Delay between reports; typically one time step but can be greater.
Can be specified in steps (e.g. 1t) or days (e.g. 5d).
duringInit=booleanUnits: Days Min: 1 Max: unbounded
Also output during initialization. By default this is disabled (only intervention-period data is output). This should not be used for predictions, but can be useful for model validation.
In this mode, 'simulation time' is output as the first column (in addition to 'timestep'), since 'timestep' is dis- continuous across the start of the intervention period.
→ scenario → monitoring → continuous → option
<option
name=string
[ value=boolean ] DEFAULT VALUE true
/>name=stringName of an option (monitoring measure or model option).
value=booleanDefault value: true
Option on/off switch (true/false). Specifying value="true" is the same as not specifying a value; specifying value="false" explicitly turns the option off. If an option is not mentioned at all, it is left at its default value (normally off, but in a few cases, such as some bug-fix options, on).
→ scenario → monitoring → SurveyOptions
<SurveyOptions>
IN THIS ORDER:
| ( <option ... /> )*
</SurveyOptions>List of all active survey options. See model/mon/OutputMeasures.h for a list of supported outputs. Should also be on the wiki.
→ scenario → monitoring → SurveyOptions → option
<option
[ outputNumber=int ]
[ byAge=boolean ]
[ byCohort=boolean ]
[ bySpecies=boolean ]
[ byGenotype=boolean ]
[ byDrugType=boolean ]
/>outputNumber=intNumber identifying this monitoring measure in the output file (3rd column). Normally this is determined from the measure, but it can be set manually, e.g. for when the same measure is recorded twice (to accumulate across different categories).
byAge=booleanIf true, the measure is reported for each age category. If false, values are summed across all age categories and only the sum reported. If not specified, separate categories will be reported if the measure supports this.
byCohort=booleanIf true, the measure is reported for each cohort separately. If false, values are summed across all cohorts and only the sum reported. If not specified, separate categories will be reported if the measure supports this.
bySpecies=booleanIf true, the measure is reported for each mosquito species separately. If false, values are summed across all species and only the sum reported. If not specified, separate categories will be reported if the measure supports this.
byGenotype=booleanIf true, the measure is reported for each parasite genotype separately. If false, values are summed across all genotypes and only the sum reported. If not specified, separate categories will be reported if the measure supports this.
byDrugType=booleanIf true, the measure is reported for each drug type separately. If false, values are summed across all drug types and only the sum reported. If not specified, separate categories will be reported if the measure supports this.
→ scenario → monitoring → surveys
<surveys
[ detectionLimit=double ]
[ diagnostic=string ]
>
IN THIS ORDER:
| ( <surveyTime ... /> )+
</surveys>List of survey times
detectionLimit=doubleUnits: parasites/microlitre Min: 0
Deprecated: limit above which a human's infection is reported as patent.
Alternative: do not specify this; instead specify "diagnostic".
diagnostic=stringName of a parameterised diagnostic to use in surveys (see scenario/diagnostics).
→ scenario → monitoring → surveys → surveyTime
<surveyTime
[ repeatStep=string ]
[ repeatEnd=string ]
[ reported=boolean ] DEFAULT VALUE true
>
string
</surveyTime>Time of a survey. A report will be made for those measures enabled under SurveyOptions. Reported data is either from the moment the survey is done (immediate data) or is collected over the time since the previous survey, or in some cases over a fixed time span (usually one year).
Times can be specified in time steps, starting from 0, or as a date (see monitoring/startDate), or in days (e.g. 15d) or years (e.g. 1y). Relative times mean the time since the start of the intervention period, and must be non-negative (zero is valid, but some measures, e.g. nUncomp, will be zero).
The simulation ends immediately after the last survey is taken.
repeatStep=stringUnits: User defined
See repeatEnd's documentation.
repeatEnd=stringUnits: User defined
Either both repeatStep and repeatEnd should be present or neither. If present, the survey is repeated every repeatStep timesteps (i.e. if t0 is the initial time and x is repeatStep, surveys are done at times t0, t0+x, t0+2*x, ...), ending before repeatEnd (final repetition is the one before repeatEnd).
Note that repeatEnd may be specified as a date but repeatStep must be a duration (days, steps or years).
reported=booleanDefault value: true
For normal surveys, reporting=true. If set false, quantities are measured but not reported. The reason for doing this is to update conditions set on reportable measures.
Multiple surveys may be given here for the same date, e.g. if using "repeatStep" for both reporting and non-reporting surveys. These are combined such that a maximum of one survey is carried out per time-step, and the survey is reported if any of the listed surveys for this date is configured as "reporting".
Note that adding non-reporting surveys will not affect value output by reported surveys, with the exception that generated psuedo-random numbers may be altered (specifically, when any stochastic diagnostics are used in surveys).
→ scenario → monitoring → ageGroup
<ageGroup
lowerbound=double
>
IN THIS ORDER:
| ( <group ... /> )+
</ageGroup>List of age groups included in demography or surveys
lowerbound=doubleUnits: Years Min: 0 Max: 100
Lower bound of age group
→ scenario → monitoring → ageGroup → group
<group
upperbound=double
/>upperbound=doubleUnits: Years Min: 0 Max: 100
Upper bound of age group
→ scenario → monitoring → cohorts
<cohorts>
IN THIS ORDER:
| ( <subPop ... /> )+
</cohorts>Allows the configuration of multiple cohorts (output segregated according to membership within specific sub-populations).
If this element is omitted, monitoring surveys cover the entire simulated human population.
It does not affect the "continuous" outputs (these never take cohorts into account).
→ scenario → monitoring → cohorts → subPop
<subPop
id=string
number=integer
/>Consider a certain sup-population a cohort, and segregate outputs according to membership. Where multiple sub-populations are listed, segregate output according to all combinations of membership: e.g. if sub-populations A and B are listed, there will be outputs for "member of A and B", "member of A but not B", "B but not A" and "not a member of A or B". Listing n sub-populations implies 2^n sets of outputs (each is further segregated by age groups, survey times and enabled output measures, which could lead to excessive program memory usage and output file size).
To identify outputs, each sub-population has a power of two number as identifier (see "number" attribute). Each of the 2^n output sets is identified by a number: the output set is the output from humans who are members in some set of sub-populations (S1, S2, ...) and not members in some others (T1, T2, ...); the number identifying the set is the sum of the numbers identifying the sets S1, S2, etc.
In the output file, the output set is identified by multiplying this number by 1000 then adding it to the age group column.
id=stringTextual identifier for the sub-population (i.e. for an intervention component, since sub-populations are defined as the hosts an intervention component is deployed to).
number=integerUnits: dimensionless Min: 1 Max: 2097152
Number identifying a sub-population; used to define identifiers of output sets. This number must be a power of 2 (i.e. 1, 2, 4, 8, ...). See documentation of subPop element.
<interventions
name=string
>
IN ANY ORDER:
| [ <changeHS ... /> ]
| [ <changeEIR ... /> ]
| [ <importedInfections ... /> ]
| [ <insertR_0Case ... /> ]
| [ <uninfectVectors ... /> ]
| [ <vectorPop ... /> ]
| [ <vectorTrap ... /> ]
| [ <human ... /> ]
</interventions>List of interventions. Generally these are either point-time distributions of something to some subset of the population, or continuous-time distribution targetting individuals when they reach a certain age.
name=stringName of set of interventions
→ scenario → interventions → changeHS
<changeHS
[ name=string ]
>
IN THIS ORDER:
| ( <timedDeployment ... /> )*
</changeHS>Changes to the health system
name=stringName of intervention
→ scenario → interventions → changeHS → timedDeployment
<timedDeployment
time=string
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <EventScheduler ... />
| | <ImmediateOutcomes ... />
| | <DecisionTree5Day ... />
| <CFR ... />
| <pSequelaeInpatient ... />
</timedDeployment>A complete replacement health system. Replaces all previous properties. (Health system can be replaced multiple times if necessary.)
Description of case management system, used to specify the initial model or a replacement (an intervention). Encompasses case management data and some other data required to derive case outcomes.
Contains a sub-element describing the particular health-system in use. Health system data is here defined as data used to decide on a treatment strategy, given a case requiring treatment.
time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this replacement occurs. See doc on intervention period and on monitoring/startDate for details of how times work.
Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → healthSystem → EventScheduler
<EventScheduler>
IN THIS ORDER:
| <uncomplicated ... />
| <complicated ... />
| <ClinicalOutcomes ... />
| [ <NonMalariaFevers ... /> ]
</EventScheduler>→ scenario → healthSystem → EventScheduler → uncomplicated
<uncomplicated
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</uncomplicated>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple
<multiple
[ name=string ]
>
IN THIS ORDER:
| ( <caseType ... /> )*
| ( <diagnostic ... /> )*
| ( <random ... /> )*
| ( <age ... /> )*
| ( <treatPKPD ... /> )*
| [ <treatSimple ... /> ]
| ( <deploy ... /> )*
</multiple>A special node allowing multiple sub-trees to be evaluated.
This is different from an ordinary decision tree node in that:
a) multiple types of child can occur simultaneously (e.g. multiple types of treatment or treatment plus a 'random' sub-tree)
b) the 'noTreatment' and 'treatFailure' nodes are not allowed
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → caseType
<caseType
[ name=string ]
>
IN ANY ORDER:
| <firstLine ... />
| <secondLine ... />
</caseType>A switch which choses a branch deterministically, based on whether the patient was treated recently (second line) or not (first line).
For uncomplicated cases only.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → caseType → firstLine
<firstLine
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</firstLine>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → caseType
<caseType
[ name=string ]
>
IN ANY ORDER:
| <firstLine ... />
| <secondLine ... />
</caseType>A switch which choses a branch deterministically, based on whether the patient was treated recently (second line) or not (first line).
For uncomplicated cases only.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → caseType → secondLine
<secondLine
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</secondLine>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → diagnostic
<diagnostic
diagnostic=string
[ name=string ]
>
IN ANY ORDER:
| <positive ... />
| <negative ... />
</diagnostic>A switch which choses a branch deterministically, based on the outcome of some type of diagnostic.
diagnostic=stringShould match the name of some parameterised diagnostic (see scenario/diagnostics).
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → diagnostic → positive
<positive
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</positive>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → random
<random
[ name=string ]
>
IN THIS ORDER:
| ( <outcome ... /> )+
</random>A switch which choses a branch randomly.
Each branch must be listed with a probability; the sum of all these probabilities must equal 1.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → random → outcome
<outcome
p=double
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</outcome>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
p=doubleUnits: None Min: 0 Max: 1
Probability of selecting this outcome. The sum of probabilities across all outcomes must be 1.
→ scenario → interventions → human → component → decisionTree → age
<age
[ name=string ]
>
IN THIS ORDER:
| ( <age ... /> )+
</age>A switch which choses a branch deterministically, based on the patient's age (in years).
Categories must uniquely cover all ages from birth, with no upper bound. Categories must be listed in order of age, increasing; the first must have lower bound 0. Upper bounds are equal to the lower bound of the next category, (but are exclusive where lower bounds are inclusive); the last category has no upper bound.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → age → age
<age
lb=double
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</age>Describes a branch, selected for patients of a certain age.
Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
lb=doubleMin: 0
→ scenario → interventions → human → component → decisionTree → noTreatment
<noTreatment
[ name=string ]
/>An end node doing nothing. This exists to explicitly state that no treatment happens and to prevent trees from accidentally being left incomplete.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → treatFailure
<treatFailure
[ name=string ]
/>An end node which reports treatment but does not change parasitalogical status. This allows correct labelling of second-line cases.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → treatPKPD
<treatPKPD
schedule=string
dosage=string
[ delay_h=double ] DEFAULT VALUE 0
/>A command to administer drugs according to a given schedule and dosage table, optionally with a delay.
schedule=stringThe name of a schedule to use for treatment.
dosage=stringThe name of a dosage table to use for treatment.
delay_h=doubleDefault value: 0
Optionally, this can be given to delay the start of treatment by a given number of hours. If not specified, treatment is not delayed. If a delay is given, all medications within the treatment schedule used are delayed by this number of hours.
→ scenario → interventions → human → component → decisionTree → treatSimple
<treatSimple
durationLiver=string
durationBlood=string
/>Simple treatment model, targetting liver- and/or blood-stage infections. This is all-or-nothing treatment which, when deploymed, completely clears all infections of the targetted stages. This makes it unsuitable for modeling resistance, but suitable for use with simple infection models.
Infections are considered liver-stage when less than five days old and blood-stage after that. Effects are described independently for the two stages.
durationLiver=stringUnits: User defined
Controls action on liver-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all liver-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
durationBlood=stringUnits: User defined
Controls action on blood-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all blood-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
→ scenario → interventions → human → component → decisionTree → deploy
<deploy
component=string
/>Deploy one or more intervention components.
component=stringThe identifier (short name) of a component.
→ scenario → interventions → human → component → decisionTree → multiple → diagnostic → negative
<negative
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</negative>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → diagnostic
<diagnostic
diagnostic=string
[ name=string ]
>
IN ANY ORDER:
| <positive ... />
| <negative ... />
</diagnostic>A switch which choses a branch deterministically, based on the outcome of some type of diagnostic.
diagnostic=stringShould match the name of some parameterised diagnostic (see scenario/diagnostics).
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → random
<random
[ name=string ]
>
IN THIS ORDER:
| ( <outcome ... /> )+
</random>A switch which choses a branch randomly.
Each branch must be listed with a probability; the sum of all these probabilities must equal 1.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → age
<age
[ name=string ]
>
IN THIS ORDER:
| ( <age ... /> )+
</age>A switch which choses a branch deterministically, based on the patient's age (in years).
Categories must uniquely cover all ages from birth, with no upper bound. Categories must be listed in order of age, increasing; the first must have lower bound 0. Upper bounds are equal to the lower bound of the next category, (but are exclusive where lower bounds are inclusive); the last category has no upper bound.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → decisionTree → multiple → treatPKPD
<treatPKPD
schedule=string
dosage=string
[ delay_h=double ] DEFAULT VALUE 0
/>A command to administer drugs according to a given schedule and dosage table, optionally with a delay.
schedule=stringThe name of a schedule to use for treatment.
dosage=stringThe name of a dosage table to use for treatment.
delay_h=doubleDefault value: 0
Optionally, this can be given to delay the start of treatment by a given number of hours. If not specified, treatment is not delayed. If a delay is given, all medications within the treatment schedule used are delayed by this number of hours.
→ scenario → interventions → human → component → decisionTree → multiple → treatSimple
<treatSimple
durationLiver=string
durationBlood=string
/>Simple treatment model, targetting liver- and/or blood-stage infections. This is all-or-nothing treatment which, when deploymed, completely clears all infections of the targetted stages. This makes it unsuitable for modeling resistance, but suitable for use with simple infection models.
Infections are considered liver-stage when less than five days old and blood-stage after that. Effects are described independently for the two stages.
durationLiver=stringUnits: User defined
Controls action on liver-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all liver-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
durationBlood=stringUnits: User defined
Controls action on blood-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all blood-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
→ scenario → interventions → human → component → decisionTree → multiple → deploy
<deploy
component=string
/>Deploy one or more intervention components.
component=stringThe identifier (short name) of a component.
→ scenario → healthSystem → EventScheduler → complicated
<complicated
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</complicated>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes
<ClinicalOutcomes>
IN THIS ORDER:
| <maxUCSeekingMemory ... />
| <uncomplicatedCaseDuration ... />
| <complicatedCaseDuration ... />
| <complicatedRiskDuration ... />
| ( <dailyPrImmUCTS ... /> )+
</ClinicalOutcomes>- maxUCSeekingMemory
- uncomplicatedCaseDuration
- complicatedCaseDuration
- complicatedRiskDuration
- dailyPrImmUCTS
Description of base parameters of the clinical model.
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes → maxUCSeekingMemory
<maxUCSeekingMemory>
int
</maxUCSeekingMemory>Maximum number of timesteps (including first day of case) that an individual with an uncomplicated case of malaria will remember he/she was sick before resetting.
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes → uncomplicatedCaseDuration
<uncomplicatedCaseDuration>
int
</uncomplicatedCaseDuration>Fixed length of an uncomplicated case of malarial or non-malarial sickness (from treatment seeking until return to life-as-usual). Usually 3.
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes → complicatedCaseDuration
<complicatedCaseDuration>
int
</complicatedCaseDuration>Fixed length of a complicated or severe case of malaria (from treatment seeking until return to life-as-usual).
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes → complicatedRiskDuration
<complicatedRiskDuration>
int
</complicatedRiskDuration>Number of days for which humans are at risk of death during a severe or complicated case of malaria. Cannot be greater than the duration of a complicated case or less than 1 day.
→ scenario → healthSystem → EventScheduler → ClinicalOutcomes → dailyPrImmUCTS
<dailyPrImmUCTS>
double
</dailyPrImmUCTS>It is sometimes desirable to model delays to treatment-seeking in uncomplicated cases. While treatment of drugs can be delayed within case management trees to provide a similar effect, this doesn't delay any of the decisions, including diagnostics using the current parasite density.
Instead a list of dailyPrImmUCTS elements can be used, describing successive daily probabilities of treatment (sum must be 1). For example, with a list of two elements with values 0.8 and 0.2, for 80% of UC cases the decision tree is evaluated immediately, and for 20% of cases evaluation is delayed by one day.
For no delay, use one element with a value of 1.
→ scenario → healthSystem → EventScheduler → NonMalariaFevers
<NonMalariaFevers>
IN THIS ORDER:
| <prTreatment ... />
| <effectNegativeTest ... />
| <effectPositiveTest ... />
| <effectNeed ... />
| <effectInformal ... />
| <CFR ... />
| <TreatmentEfficacy ... />
</NonMalariaFevers>Description of non-malaria fever health-system modelling (treatment, outcomes and costing). Incidence is described by the model->clinical->NonMalariaFevers element. Non-malaria fevers are only modelled if the NON_MALARIA_FEVERS option is used.
As further explanation of the parameters below, we first take: β₀ = logit(P₀) - β₃·P(need), and then calculate the probability of antibiotic administration, P(AB), dependent on treatment seeking location. No seeking: P(AB) = 0 Informal sector: logit(P(AB)) = β₀ + β₄ Health facility: logit(P(AB)) = β₀ + β₁·I(neg) + β₂·I(pos) + β₃·I(need) (where I(X) is 1 when event X is true and 0 otherwise, logit(p)=log(p/(1-p)), event "need" is the event that death may occur without treatment, events "neg" and "pos" are the events that a malaria parasite diagnositic was used and indicated no parasites and parasites respectively).
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → prTreatment
<prTreatment>
double
</prTreatment>Probability of a non-malaria fever being treated with an antibiotic given that no malaria diagnostic was used but independent of need. Symbol: P₀.
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → effectNegativeTest
<effectNegativeTest>
double
</effectNegativeTest>The effect of a negative malaria diagnostic on the odds ratio of receiving antibiotics. Symbol: exp(β₁).
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → effectPositiveTest
<effectPositiveTest>
double
</effectPositiveTest>The effect of a positive malaria diagnostic on the odds ratio of receiving antibiotics. Symbol: exp(β₂).
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → effectNeed
<effectNeed>
double
</effectNeed>The effect of needing antibiotic treatment on the odds ratio of receiving antibiotics. Symbol: exp(β₃).
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → effectInformal
<effectInformal>
double
</effectInformal>The effect of seeking treatment from an informal provider (i.e. a provider untrained in NMF diagnosis) on the odds ratio of receiving antibiotics. Symbol: exp(β₄)
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → CFR
<CFR
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</CFR>Base case fatality rate for non-malaria fevers (probability of death from a fever requiring antibiotic treatment given that no antibiotic treatment is received, per age-group).
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → healthSystem → CFR → group
<group
lowerbound=double
/>A series of values according to age groups, each specified with a lower-bound and a value. The first lower-bound specified must be zero; a final upper-bound of infinity is added to complete the last age group. At least one age group is required. Normally these are interpolated by a continuous function (see interpolation attribute).
lowerbound=doubleUnits: Years Min: 0 Max: 100
Lower bound of age group
→ scenario → healthSystem → EventScheduler → NonMalariaFevers → TreatmentEfficacy
<TreatmentEfficacy>
double
</TreatmentEfficacy>Probability that treatment would prevent a death (i.e. CFR is multiplied by one minus this when treatment occurs).
→ scenario → healthSystem → ImmediateOutcomes
<ImmediateOutcomes
[ name=string ]
[ useDiagnosticUC=boolean ] DEFAULT VALUE false
>
IN ANY ORDER:
| <drugRegimen ... />
| <initialACR ... />
| <compliance ... />
| <nonCompliersEffective ... />
| <treatmentActions ... />
| <pSeekOfficialCareUncomplicated1 ... />
| <pSelfTreatUncomplicated ... />
| <pSeekOfficialCareUncomplicated2 ... />
| <pSeekOfficialCareSevere ... />
| [ <liverStageDrug ... /> ]
</ImmediateOutcomes>- drugRegimen
- initialACR
- compliance
- nonCompliersEffective
- treatmentActions
- pSeekOfficialCareUncomplicated1
- pSelfTreatUncomplicated
- pSeekOfficialCareUncomplicated2
- pSeekOfficialCareSevere
- liverStageDrug
Description of "immediate outcomes" health system: Tediosi et al case management model (Case management as described in AJTMH 75 (suppl 2) pp90-103).
name=stringName of health system
useDiagnosticUC=booleanDefault value: false
→ scenario → healthSystem → ImmediateOutcomes → drugRegimen
<drugRegimen
firstLine=string
secondLine=string
inpatient=string
/>Description of drug regimen.
firstLine=stringUnits: Drug code
Code for first line drug
secondLine=stringUnits: Drug code
Code for second line drug
inpatient=stringUnits: Drug code
Code for drug used for treating inpatients
→ scenario → healthSystem → ImmediateOutcomes → initialACR
<initialACR>
IN THIS ORDER:
| [ <CQ ... /> ]
| [ <SP ... /> ]
| [ <AQ ... /> ]
| [ <SPAQ ... /> ]
| [ <ACT ... /> ]
| [ <QN ... /> ]
| <selfTreatment ... />
</initialACR>Initial cure rate
→ scenario → healthSystem → ImmediateOutcomes → initialACR → CQ
<CQ
value=double
/>Chloroquine
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → SP
<SP
value=double
/>Sulphadoxine-pyrimethamine
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → AQ
<AQ
value=double
/>Amodiaquine
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → SPAQ
<SPAQ
value=double
/>Sulphadoxine-pyrimethamine/Amodiaquine
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → ACT
<ACT
value=double
/>Artemisinine combination therapy
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → QN
<QN
value=double
/>Quinine
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → initialACR → selfTreatment
<selfTreatment
value=double
/>Probability of self-treatment
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → compliance
<compliance>
IN THIS ORDER:
| [ <CQ ... /> ]
| [ <SP ... /> ]
| [ <AQ ... /> ]
| [ <SPAQ ... /> ]
| [ <ACT ... /> ]
| [ <QN ... /> ]
| <selfTreatment ... />
</compliance>Adherence to treatment
→ scenario → healthSystem → ImmediateOutcomes → nonCompliersEffective
<nonCompliersEffective>
IN THIS ORDER:
| [ <CQ ... /> ]
| [ <SP ... /> ]
| [ <AQ ... /> ]
| [ <SPAQ ... /> ]
| [ <ACT ... /> ]
| [ <QN ... /> ]
| <selfTreatment ... />
</nonCompliersEffective>Effectiveness of treatment for non-compliant patients
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions
<treatmentActions>
IN ANY ORDER:
| [ <CQ ... /> ]
| [ <SP ... /> ]
| [ <AQ ... /> ]
| [ <SPAQ ... /> ]
| [ <ACT ... /> ]
| [ <QN ... /> ]
</treatmentActions>→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → CQ
<CQ
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</CQ>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → CQ → deploy
<deploy
[ maxAge=double ]
[ minAge=double ] DEFAULT VALUE 0
[ p=double ] DEFAULT VALUE 1
>
IN THIS ORDER:
| ( <component ... /> )+
</deploy>maxAge=doubleUnits: Years Min: 0
Maximum age of eligible humans (defaults to no limit).
Input is rounded to the nearest time step.
minAge=doubleUnits: Years Min: 0 Default value: 0
Minimum age of eligible humans (defaults to 0).
Input is rounded to the nearest time step.
p=doubleUnits: dimensionless Min: 0 Max: 1 Default value: 1
Probability of this list of components being deployed, given that other constraints are met.
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → CQ → deploy → component
<component
id=string
/>The list of components deployed to eligible humans.
id=stringThe identifier (short name) of a component.
→ scenario → healthSystem → DecisionTree5Day → treatmentSevere → clearInfections
<clearInfections
timesteps=string
stage=("liver" or "blood" or "both")
/>This clears infections according to several options: it can clear all blood stage infections, all liver stage infections or both, and it can act on multiple timesteps. To have a probability of no action add another treatment option (which does nothing) and set the probabilities of selection appropriately.
This allows immediate (legacy) or delayed action, a prophylactic period, and selection of which stages are targeted. It is a simple model but appropriate enough for use with the five day timestep when assuming no resistance and that drug failure is mainly caused by bad drugs or compliance.
The old treatment action for the five-day timestep model is essentially this, with immediateAction (timesteps=-1) and stage=both, except for the IPT model's SP action, which was more like with timesteps>1 and stage=blood.
timesteps=stringUnits: User defined (defaults to steps)
The number of timesteps during which this action remains in effect (e.g. 2 means clear infections during the next two timestep updates). Full clearance of the targeted stages occurs during this time.
A special value of -1 means act immediately (retrospectively); this the old behaviour. A value of 1 means act on the next timestep only.
Both of these can be thought of as a model for short-acting effective drug treatment; the main differences are that the latter means parasite densities will remain high from the point of view of surveys and diagnostics (i.e. mass screen and treat) used before the next timestep and that the latter will also remove infections starting the next timestep. Arguably the latter is a better model, but the differences are perhaps small, excepting where immediate treatment of fevers (i.e. through the health system) can hide high parasite densities from reporting and mass-screen-and-treat diagnostics. For use by interventions, the latter model has nicer behaviour in that the order of deployment of multiple interventions deployed at the same time does not matter, and that the former model retrospectively treats infections which may already have caused fever, thus may have a lower health impact than it should.
It is recommended to use the new model (value 1, or greater than 1 if prophylactic effect is desired) unless wanting to emulate the old behaviour.
Values of 0 or less than -1 are not allowed.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
stage=("liver" or "blood" or "both")Controls whether liver-stage or blood-stage infections are cleared, or both.
Infections are considered liver-stage for one 5-day timestep, blood-stage but pre-patent for some number of timesteps (latentp - 1), then start the patent blood stage. If stage is set to "liver", infections are only cleared during their first timestep; if stage is set to "blood", infections are cleared during pre-patent and patent blood stages; if stage is set to "both" all infections are cleared.
The old behaviour (oddly considering the drugs it is meant to emulate) is to clear both stages, except for the IPT model of SP action, which cleared only patent blood-stage infections.
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → SP
<SP
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</SP>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → AQ
<AQ
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</AQ>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → SPAQ
<SPAQ
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</SPAQ>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → ACT
<ACT
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</ACT>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → treatmentActions → QN
<QN
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</QN>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → ImmediateOutcomes → pSeekOfficialCareUncomplicated1
<pSeekOfficialCareUncomplicated1
value=double
/>Probability that a patient with newly incident uncomplicated disease seeks official care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → pSelfTreatUncomplicated
<pSelfTreatUncomplicated
value=double
/>Probability that a patient with uncomplicated disease without recent history of disease (i.e. first line) will self-treat.
Note that in second line cases there is no probability of self-treatment.
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → pSeekOfficialCareUncomplicated2
<pSeekOfficialCareUncomplicated2
value=double
/>Probability that a patient with recurrence of uncomplicated disease seeks official care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → pSeekOfficialCareSevere
<pSeekOfficialCareSevere
value=double
/>Probability that a patient with severe disease obtains appropriate care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → liverStageDrug
<liverStageDrug>
IN ANY ORDER:
| <pHumanCannotReceive ... />
| [ <ignoreCannotReceive ... /> ]
| [ <pUseUncomplicated ... /> ]
| <effectivenessOnUse ... />
</liverStageDrug>Parameters for drug treatment which have an effect on the liver-stage of parasites (Primaquine and potentially Tafenoquine); for use with the Vivax model only.
Note: if this section is not listed, the following default values are assumed: pHumanCannotReceive=0, pUseUncomplicated=0, effectivenessOnUse=1.
→ scenario → healthSystem → ImmediateOutcomes → liverStageDrug → pHumanCannotReceive
<pHumanCannotReceive
value=double
/>Chance that a human is determined to be unable to receive liver-stage drug treatment. Treatment is neither reported or given for such humans.
This is sampled once per human at birth.
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → liverStageDrug → ignoreCannotReceive
<ignoreCannotReceive
value=boolean
/>If true, ignore pHumanCannotReceive and consider all humans eligible for treatment; if false (or not specified), do not treat those demed incompatible with liver-stage drug treatment.
The point of this is that pHumanCannotReceive cannot be altered by changeHS interventions, but this property can be.
value=booleanA boolean value.
→ scenario → healthSystem → ImmediateOutcomes → liverStageDrug → pUseUncomplicated
<pUseUncomplicated
value=double
/>This feature is deprecated; it is suggested to use the "simple treatment" feature configured to clear liver-stage parasites, leaving this option unset or zero.
Chance of liver-stage drug treatment being used for routine treatment of an uncomplicated case.
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → ImmediateOutcomes → liverStageDrug → effectivenessOnUse
<effectivenessOnUse
value=double
/>Chance that liver-stage drug treatment is effective.
On application, a random variable is sampled against this probability. If false, the treatment does nothing; if true, the treatment clears all liver stage parasites. Where effectiveness is longer than a single time step (prophylactic effect), this sample still only happens once (thus either no effect or all liver stages cleared over multiple steps).
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day
<DecisionTree5Day
[ name=string ]
>
IN ANY ORDER:
| <pSeekOfficialCareUncomplicated1 ... />
| <pSelfTreatUncomplicated ... />
| <pSeekOfficialCareUncomplicated2 ... />
| <pSeekOfficialCareSevere ... />
| [ <liverStageDrug ... /> ]
| <treeUCOfficial ... />
| <treeUCSelfTreat ... />
| <cureRateSevere ... />
| <treatmentSevere ... />
</DecisionTree5Day>- pSeekOfficialCareUncomplicated1
- pSelfTreatUncomplicated
- pSeekOfficialCareUncomplicated2
- pSeekOfficialCareSevere
- liverStageDrug
- treeUCOfficial
- treeUCSelfTreat
- cureRateSevere
- treatmentSevere
Description of the health system using the 5-day timestep with decision tree model: access is configured as in the Tediosi et al case management model (Case management as described in AJTMH 75 (suppl 2) pp90-103) while treatment decisions are configured via decision trees.
Besides greater flexibility, this allows treatment via PK/PD models.
name=stringName of health system
→ scenario → healthSystem → DecisionTree5Day → pSeekOfficialCareUncomplicated1
<pSeekOfficialCareUncomplicated1
value=double
/>Probability that a patient with newly incident uncomplicated disease seeks official care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day → pSelfTreatUncomplicated
<pSelfTreatUncomplicated
value=double
/>Probability that a patient with uncomplicated disease without recent history of disease (i.e. first line) will self-treat.
Note that in second line cases there is no probability of self-treatment.
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day → pSeekOfficialCareUncomplicated2
<pSeekOfficialCareUncomplicated2
value=double
/>Probability that a patient with recurrence of uncomplicated disease seeks official care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day → pSeekOfficialCareSevere
<pSeekOfficialCareSevere
value=double
/>Probability that a patient with severe disease obtains appropriate care
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day → liverStageDrug
<liverStageDrug>
IN ANY ORDER:
| <pHumanCannotReceive ... />
| [ <ignoreCannotReceive ... /> ]
| [ <pUseUncomplicated ... /> ]
| <effectivenessOnUse ... />
</liverStageDrug>Parameters for drug treatment which have an effect on the liver-stage of parasites (Primaquine and potentially Tafenoquine); for use with the Vivax model only.
Note: if this section is not listed, the following default values are assumed: pHumanCannotReceive=0, pUseUncomplicated=0, effectivenessOnUse=1.
→ scenario → healthSystem → DecisionTree5Day → treeUCOfficial
<treeUCOfficial
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</treeUCOfficial>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → healthSystem → DecisionTree5Day → treeUCSelfTreat
<treeUCSelfTreat
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</treeUCSelfTreat>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → healthSystem → DecisionTree5Day → cureRateSevere
<cureRateSevere
value=double
/>The probability of clearing parasites given access to appropriate (hospital) care, for a severe case.
value=doubleA double-precision floating-point value.
→ scenario → healthSystem → DecisionTree5Day → treatmentSevere
<treatmentSevere
[ name=string ]
>
IN THIS ORDER:
| ( <deploy ... /> )*
</treatmentSevere>Describes the effects of the treatment, assuming this compliance/adherence/... option is selected. Effects are described in terms of a list of options, each of which acts independently but with all effects being activated simultaneously.
Lists intervention components which are deployed according to some external trigger (for example, screening with a negative patency outcome or health-system treatment).
Components are referenced from one or more sub-lists. Each of these lists is deployed independently if and only if its age constraints are met by the human host and a random sample with the given probability of a positive outcome is positive.
name=stringDescribes what this compliance option represents (e.g. "good compliance", "poor compliance with good drugs", ...).
→ scenario → healthSystem → CFR
<CFR
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</CFR>Case fatality rate (probability of an inpatient fatality from a bout of severe malaria, per age-group).
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → healthSystem → pSequelaeInpatient
<pSequelaeInpatient
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</pSequelaeInpatient>List of age-specific probabilities of sequelae in inpatients, during a severe bout of malaria.
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → interventions → changeEIR
<changeEIR
[ name=string ]
>
IN THIS ORDER:
| ( <timedDeployment ... /> )*
</changeEIR>New description of transmission level for models not supporting vector control interventions. Use of this overrides previous transmission levels such that human infectiousness no longer has any feedback effect on transmission. Supplied EIR data must last until end of simulation.
name=stringName of intervention
→ scenario → interventions → changeEIR → timedDeployment
<timedDeployment
time=string
>
IN THIS ORDER:
| ( <EIRDaily ... /> )+
</timedDeployment>Replacement transmission levels. Disables feedback of human infectiousness to mosquitoes on further mosquito to human transmission. Must last until end of simulation.
time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this replacement occurs. See doc on intervention period and on monitoring/startDate for details of how times work.
Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → entomology → nonVector → EIRDaily
<EIRDaily
[ origin=string ]
>
double
</EIRDaily>In the non-vector model, EIR is input as a sequence of daily values. There must be at least one years' worth of entries (365), and if there are more, values are wrapped and averaged (i.e. value for first day of year is taken as the mean of values for days 0, 365+0, 2*365+0, etc.).
origin=string→ scenario → interventions → importedInfections
<importedInfections
[ name=string ]
>
IN THIS ORDER:
| <timed ... />
</importedInfections>Models importation of P. falciparum infections directly into humans from an external source. This is infections, not inoculations or EIR being imported.
name=stringName of intervention
→ scenario → interventions → importedInfections → timed
<timed
[ period=string ] DEFAULT VALUE 0
>
IN THIS ORDER:
| ( <rate ... /> )+
</timed>Rate of case importation, as a step function. Each value is valid until replaced by the next value.
period=stringUnits: User defined (default: steps) Min: 0 Default value: 0
If period is 0 (or effectively infinite), the last specified value remains indefinitely in effect, otherwise the times of all values specified must be less than the period, and values are repeated modulo period (the step at time 'period+2t' has same value as the step at '2t', etc.).
Can be specified in steps (e.g. 1t) or days (e.g. 365d).
→ scenario → interventions → importedInfections → timed → rate
<rate
time=string
/>A time-rate pair.
time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this importation rate becomes active.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → interventions → insertR_0Case
<insertR_0Case
[ name=string ]
>
IN THIS ORDER:
| ( <timedDeployment ... /> )*
</insertR_0Case>Used to simulate R_0. First, infections should be eliminated, immunity removed, and the population given an effective transmission- blocking vaccine (not done by this intervention). Then this intervention may be used to: pick one human, infect him, administer a fully effective Preerythrocytic vaccine and remove transmission-blocking vaccine effect on this human. Thus only this one human will be a source of infections in an unprotected population, and will not reinfected himself.
name=stringName of intervention
→ scenario → interventions → insertR_0Case → timedDeployment
<timedDeployment
time=string
/>time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this intervention occurs.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → interventions → uninfectVectors
<uninfectVectors
[ name=string ]
>
IN THIS ORDER:
| ( <timedDeployment ... /> )*
</uninfectVectors>Removes all infections from mosquitoes -- resulting in zero EIR to humans, until such time that mosquitoes are re-infected and become infectious. Only efficacious in dynamic EIR mode (when changeEIR was not used).
Hypothetical, but potentially useful to simulate a setting starting from no infections, but with enough mosquitoes to reach a set equilibrium of exposure.
name=stringName of intervention
→ scenario → interventions → uninfectVectors → timedDeployment
<timedDeployment
time=string
/>time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this intervention occurs.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → interventions → vectorPop
<vectorPop>
IN THIS ORDER:
| ( <intervention ... /> )+
</vectorPop>A list of parameterisations of generic vector host-inspecific interventions.
→ scenario → interventions → vectorPop → intervention
<intervention
name=string
>
IN THIS ORDER:
| <description ... />
| [ <timed ... /> ]
</intervention>An intervention which may have various effects on the vector populations as a whole. (Not host specific.)
Multiple instances of this intervention class are allowed (multiple parameterisations, not just deployments).
Each instance may have multiple deployments. In this case the effects of each instance are independent (effects are combined) but the effects of multiple deployments of a single instance are not independent (only the latest deployment has any effect).
name=stringName of intervention (e.g. larviciding, sugar bait).
→ scenario → interventions → vectorPop → intervention → description
<description>
IN THIS ORDER:
| ( <anopheles ... /> )+
</description>→ scenario → interventions → vectorPop → intervention → description → anopheles
<anopheles
mosquito=string
>
IN ANY ORDER:
| [ <seekingDeathRateIncrease ... /> ]
| [ <probDeathOvipositing ... /> ]
| [ <emergenceReduction ... /> ]
</anopheles>Descriptions of the effects of vector interventions with per-species effects.
mosquito=stringName of the species/subspecies/variant.
→ scenario → interventions → vectorPop → intervention → description → anopheles → seekingDeathRateIncrease
<seekingDeathRateIncrease
initial=double
>
IN THIS ORDER:
| <decay ... />
</seekingDeathRateIncrease>Describe an effect on the increase in the death rate while host seeking (mu_vA) due to this intervention.
Enter the rate increase (i.e. if rate increases to 120% of normal, give 0.2). New death rate while seeking is old × (1 + increase) where increase is this factor given. Must have increas ≥ -1.
initial=doubleUnits: dimensionless Min: -1 Max: inf
→ scenario → interventions → vectorPop → intervention → description → anopheles → seekingDeathRateIncrease → decay
<decay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → vectorPop → intervention → description → anopheles → probDeathOvipositing
<probDeathOvipositing
initial=double
>
IN THIS ORDER:
| <decay ... />
</probDeathOvipositing>Describe an effect of increased mortality while ovipositing due to this intervention. Enter the probability of dying due to this intervention.
initial=doubleUnits: dimensionless Min: 0 Max: 1
→ scenario → interventions → vectorPop → intervention → description → anopheles → probDeathOvipositing → decay
<decay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → vectorPop → intervention → description → anopheles → emergenceReduction
<emergenceReduction
initial=double
>
IN THIS ORDER:
| <decay ... />
</emergenceReduction>Describe an effect on emergence of pupa into adults: this value is the proportion of emerging pupa which are killed by this intervention.
This can be used as a crude way of modelling larviciding. It ca also be used to increase emergence by giving a negative value. The emergence rate is "old rate" × (1 - factor) where factor is the value given here; thus, for example, using -1 will double emergence.
initial=doubleUnits: dimensionless Min: -inf Max: 1
→ scenario → interventions → vectorPop → intervention → description → anopheles → emergenceReduction → decay
<decay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → vectorPop → intervention → timed
<timed>
IN THIS ORDER:
| ( <deploy ... /> )+
</timed>List of timed vector population intervention deployment
→ scenario → interventions → vectorPop → intervention → timed → deploy
<deploy
time=string
/>time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this deployment occurs.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → interventions → vectorTrap
<vectorTrap>
IN THIS ORDER:
| ( <intervention ... /> )+
</vectorTrap>Traps attract and kill mosquitoes. They are modelled as a non-human-host where the probability of mosquitoes surviving feeding is zero (since otherwise the simulator would assume surviving mosquitoes have had a blood meal), and where this "host" is initially not present.
Model: each type of trap has has an initial availability relative to a human and a decay in availability. Each deployment has a fixed maximum lifespan, after which the traps from that deployment are removed (it is up to the user whether this is after availability is effectively zero or sooner, either coinciding with a redeployment or causing a reduction in overall effectiveness of traps).
→ scenario → interventions → vectorTrap → intervention
<intervention
[ name=string ]
>
IN THIS ORDER:
| ( <description ... /> )+
| [ <timed ... /> ]
</intervention>Parameters and deployment of one type of trap. In case multiple types of trap are needed simultaneously, multiple elements can be used. Note that different types of trap do not interact except that all will attract mosquitoes.
name=stringOptional name for this type of trap
→ scenario → interventions → vectorTrap → intervention → description
<description
mosquito=string
>
IN THIS ORDER:
| <relativeAvailability ... />
| <decayOfAvailability ... />
</description>Parameters associated with a vector trap intervention, per mosquito species.
mosquito=stringName of the species/subspecies/variant.
→ scenario → interventions → vectorTrap → intervention → description → relativeAvailability
<relativeAvailability
value=double
/>Describes the availiability of a trap to a host-seeking mosquito relative to an average unprotected adult.
I.e. if this parameter is 2, then each trap will on average attract twice as many mosquitoes as unprotected adults.
This is the initial availability; it may decay towards zero depending on the configured decay function.
value=doubleA double-precision floating-point value.
→ scenario → interventions → vectorTrap → intervention → description → decayOfAvailability
<decayOfAvailability
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Describes how availability decays to zero.
If decay heterogeneity/variance is used, there will be a sample once-per-deployment (i.e. all traps of the same deployment will be affected the same way). There is no support for variances between traps (except in this crude way, between deployments).
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → vectorTrap → intervention → timed
<timed>
IN THIS ORDER:
| ( <deploy ... /> )*
</timed>List of timed vector trap intervention deployment
→ scenario → interventions → vectorTrap → intervention → timed → deploy
<deploy
ratioToHumans=double
lifespan=string
/>ratioToHumans=doubleMin: 0 Max: inf
The number of traps deployed, by this deployment, per adult human.
E.g. if there are currently 100 traps and 1000 humans, then a ratio of 0.1 will increase the number of traps to 200.
lifespan=stringUnits: Steps or Days or Years
Life of the trap until replaced or removed, e.g. "73t" or "1y". After this time period, these traps will be removed from the simulation.
New deployments do not automatically remove old traps. Existing traps cannot be refurbished in the model. It may make sense to make the end-of-life coincide with a new deployment.
→ scenario → interventions → human
<human>
IN THIS ORDER:
| ( <component ... /> )+
| ( <deployment ... /> )*
</human>Encapsulates all interventions whose effects are specific to the human host: any interventions where target humans may be selected via population-coverage, age limits and sub-population membership.
→ scenario → interventions → human → component
<component
id=string
[ name=string ]
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <screen ... />
| | <treatSimple ... />
| | <treatPKPD ... />
| | <decisionTree ... />
| | <PEV ... />
| | <BSV ... />
| | <TBV ... />
| | <ITN ... />
| | <IRS ... />
| | <GVI ... />
| | [ <recruitmentOnly ... /> ]
| | <clearImmunity ... />
| [ <subPopRemoval ... /> ]
</component>- screen
- treatSimple
- treatPKPD
- decisionTree
- PEV
- BSV
- TBV
- ITN
- IRS
- GVI
- recruitmentOnly
- clearImmunity
- subPopRemoval
A parameterisation of an effect achieved by one component of an intervention. (An intervention is described as the effects of a set of components plus deployments of those components. This describes the components individually, not deployments or which components comprise an intervention.)
Each element describes one component: its effects, decay of the(se) effect(s), and related stuff (e.g. description of indirect decay and of usage levels).
Different interventions can deploy the same component to the same perso. In most cases this will just deploy a fresh instance (e.g. a new bed net will replace the old (nobody uses multiple bed nets), or a new drug dose will act on top of previous doses, or in the case of a vaccine, effect depends on the total number of previous inoculations (including from other interventions).
Where multiple components of the same type (but with different ids) are deployed (whether within a single intervention or by multiple interventions), they act independently (e.g. two bed nets deployed to a single host would act to reduce attractiveness or survival of mosquitoes biting that host twice — this may be useful to simulate some novel vector intervention since the two nets may have separate parameters).
id=stringA short name or code identifying the intervention component (used to refer to this component when describing an intervention). Also the id of the sub-population defined as those hosts who have received this intervention and who haven't subsequently been removed from the sub-population.
name=stringAn informal name/description for the component
→ scenario → interventions → human → component → screen
<screen
diagnostic=string
>
IN THIS ORDER:
| ( <positive ... /> )*
| ( <negative ... /> )*
</screen>This can be combined with MDA to achieve mass screen and treat (MSAT) or other types of mass screening intervention.
When deployed to a host, this simulates a test of patent malaria (microscopy, RDT or some such), then triggers deployment of whichever intervention components are configured (deployments for both positive and negative test outcomes can be configured).
The use of the screening itself is reported (if enabled), but not the outcome. Deployment of interventions triggered by the screening may be reported, however.
diagnostic=stringName of a parameterised diagnostic (see scenario/diagnostics).
→ scenario → interventions → human → component → screen → positive
<positive
id=string
/>The list of components deployed to eligible humans.
id=stringThe identifier (short name) of a component.
→ scenario → interventions → human → component → screen → negative
<negative
id=string
/>The list of components deployed to eligible humans.
id=stringThe identifier (short name) of a component.
→ scenario → interventions → human → component → treatSimple
<treatSimple
durationLiver=string
durationBlood=string
/>Simple treatment model, targetting liver- and/or blood-stage infections. This is all-or-nothing treatment which, when deploymed, completely clears all infections of the targetted stages. This makes it unsuitable for modeling resistance, but suitable for use with simple infection models.
Infections are considered liver-stage when less than five days old and blood-stage after that. Effects are described independently for the two stages.
durationLiver=stringUnits: User defined
Controls action on liver-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all liver-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
durationBlood=stringUnits: User defined
Controls action on blood-stage infections. 0 means no action, -1 step is a compatibility option to act like treatment before schema version 32 (which removed infections retrospectively), 1 step or any duration which equals some whole number of steps n>0 means to clear all blood-stage infections found on the next 1 or n steps.
Note on -1 compatibility option: the main difference to 1 step (clearing on the next timestep) is that parasite densities will be reduced immediately, and thus from the point of view of surveys and mass screen and treat interventions a peak in density which is immediately treated through case management will not be seen.
Can be specified in steps (e.g. 1t, -1t) or days (e.g. 5d).
→ scenario → interventions → human → component → treatPKPD
<treatPKPD
schedule=string
dosage=string
[ delay_h=double ] DEFAULT VALUE 0
/>A command to administer drugs according to a given schedule and dosage table, optionally with a delay.
schedule=stringThe name of a schedule to use for treatment.
dosage=stringThe name of a dosage table to use for treatment.
delay_h=doubleDefault value: 0
Optionally, this can be given to delay the start of treatment by a given number of hours. If not specified, treatment is not delayed. If a delay is given, all medications within the treatment schedule used are delayed by this number of hours.
→ scenario → interventions → human → component → decisionTree
<decisionTree
[ name=string ]
>
EXACTLY ONE OF:
| <multiple ... />
| <caseType ... />
| <diagnostic ... />
| <random ... />
| <age ... />
| <noTreatment ... />
| <treatFailure ... />
| ( <treatPKPD ... /> )+
| <treatSimple ... />
| ( <deploy ... /> )+
</decisionTree>Describes how "decisions" are made, both probabilistically and deterministically, and what actions are carried out.
Quantities may also be reported as a side effect of decisions made in the tree, for example the number of diagnostics used.
name=stringAn optional piece of documentation attached to this node.
→ scenario → interventions → human → component → PEV
<PEV>
IN THIS ORDER:
| <decay ... />
| <efficacyB ... />
| ( <initialEfficacy ... /> )+
</PEV>Pre-erythrocytic vaccine (PEV): prevents a proportion of infections from commencing.
Description of a vaccine's effect
→ scenario → interventions → human → component → PEV → decay
<decay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Specification of decay of efficacy. Documentation: see DecayFunction type or https://github.com/SwissTPH/openmalaria/wiki/ModelDecayFunctions
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → human → component → PEV → efficacyB
<efficacyB
value=double
/>Measure of variation in vaccine efficacy: efficacy is sampled from a beta distribution with efficacyB its beta parameter and its alpha parameter fixed such that the mean is that given by initialEfficacy.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → PEV → initialEfficacy
<initialEfficacy
value=double
/>Mean efficacy values before decay (see efficacyB and decay parameter descriptions for sampling and decay). The i-th value in this list is used for the efficacy of the vaccine after the i-th dose. Where more doses are given than there are values in this list, the last value is repeated.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → BSV
<BSV>
IN THIS ORDER:
| <decay ... />
| <efficacyB ... />
| ( <initialEfficacy ... /> )+
</BSV>Blood-stage vaccine (BSV): acts as a killing factor on blood-stage parasites. Exact action depends on the within host model.
Description of a vaccine's effect
→ scenario → interventions → human → component → TBV
<TBV>
IN THIS ORDER:
| <decay ... />
| <efficacyB ... />
| ( <initialEfficacy ... /> )+
</TBV>Transmission-blocking vaccine (TBV): one minus this scales the probability of transmission to mosquitoes
Description of a vaccine's effect
→ scenario → interventions → human → component → ITN
<ITN>
IN THIS ORDER:
| [ <usage ... /> ]
| <holeRate ... />
| <ripRate ... />
| <ripFactor ... />
| <initialInsecticide ... />
| <insecticideDecay ... />
| <attritionOfNets ... />
| ( <anophelesParams ... /> )+
</ITN>- usage
- holeRate
- ripRate
- ripFactor
- initialInsecticide
- insecticideDecay
- attritionOfNets
- anophelesParams
Description of bed-net interventions (ITNs, LLINs).
→ scenario → interventions → human → component → ITN → usage
<usage
value=double
/>Usage of nets by humans, from 0 to 1.
At the moment this is constant across humans and deterministic: relative attractiveness and survival factors are base*(1-usagepropActing) + intervention_factorusage*propActing.
See also "propActing" (proportion of bits for which net acts).
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → ITN → holeRate
<holeRate
mean=double
sigma=double
/>The rate at which new holes are made in nets.
nHoles(t) = nHoles(t-1) + X where X~Pois(R/T) where T is the number of time-steps per year. R is sampled from log-normal: R ~ log N( log(mean)-sigma²/2, sigma² ) and is covariant with ripRate and insecticideDecay. (To be exact, a single Gaussian sample is taken, adjusted for each sigma then exponentiated.)
Parameters of a log-normal distribution.
Variates are sampled as: X ~ ln N( log(mean)-sigma²/2, sigma² ).
Equivalent R sample: rlnorm(n, log(m) - s*s/2, s)
mean=doubleUnits: (same as base units)
The mean of the lognormal distribution.
sigma=doubleSigma parameter of the lognormal distribution; sigma squared is the variance of the log of samples.
→ scenario → interventions → human → component → ITN → ripRate
<ripRate
mean=double
sigma=double
/>Each existing hole has a probability of being ripped bigger according to a Poisson process with this rate as (only) parameter.
New rips occur in a net at rate X~Pois(h×R/T) where h is the number of existing holes and T the number of time-steps per year. R is sampled from log-normal: R ~ log N( log(mean)-sigma²/2, sigma² ) and is covariant with holeRate and insecticideDecay. (To be exact, a single Gaussian sample is taken, adjusted for the each and sigma then exponentiated.)
Parameters of a log-normal distribution.
Variates are sampled as: X ~ ln N( log(mean)-sigma²/2, sigma² ).
Equivalent R sample: rlnorm(n, log(m) - s*s/2, s)
mean=doubleUnits: (same as base units)
The mean of the lognormal distribution.
sigma=doubleSigma parameter of the lognormal distribution; sigma squared is the variance of the log of samples.
→ scenario → interventions → human → component → ITN → ripFactor
<ripFactor
value=double
/>This factor expresses how important rips are in increasing the hole.
The hole index of a net is h + F×x where h and x are the total numbers of holes and rips respectively and F is the rip factor.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → ITN → initialInsecticide
<initialInsecticide
mu=double
sigma=double
/>The insecticide concentration of new nets is Gaussian distributed with mean "mu" and a standard deviation "sigma". The standard deviation should be small relative to the mean to avoid negative initial concentration. Any negative values sampled are set to 0.
Parameters of a normal distribution.
Variates are sampled as: X ~ N( mu, sigma² ).
mu=doubleUnits: (same as base units)
The mean of the normal distribution.
sigma=doubleUnits: (same as base units)
The standard deviation of variates.
→ scenario → interventions → human → component → ITN → insecticideDecay
<insecticideDecay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Decay curve for insecticide content of nets. Documentation: see DecayFunction type or https://github.com/SwissTPH/openmalaria/wiki/ModelDecayFunctions
The distribution of decay rates over nets is covariant with the distribution of ripRate and holeRate over nets. This distribution is generated by taking one sample per net from a Gaussian distribution with mean 0 and standard deviation 1. For each variable, the sample is multiplied by the respective sigma and a constant added such that, once exponentiated, the mean of the variable over nets is 1. The variable is then exponentiated and multiplied by the required mean rate for the respective variable.
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → human → component → ITN → attritionOfNets
<attritionOfNets
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Specifies the rate at which nets are disposed of over time. Documentation: see DecayFunction type or https://github.com/SwissTPH/openmalaria/wiki/ModelDecayFunctions
In the current model, nets are disposed of randomly (no correlation with state of decay) such that the chance of each net surviving until age t is the value of this decay function at time t. Equivalently (where a large number of nets are distributed at the same time), the proportion of nets remaining in use should match this decay function over time.
Humans are removed from the intervention component's sub-population on disposal (attrition) of their nets. Currently this event is not reported.
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → human → component → ITN → anophelesParams
<anophelesParams
mosquito=string
[ propActive=double ] DEFAULT VALUE 1
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <deterrency ... />
| | <twoStageDeterrency ... />
| <preprandialKillingEffect ... />
| <postprandialKillingEffect ... />
</anophelesParams>mosquito=stringName of the affected anopheles-mosquito species.
propActive=doubleUnits: dimensionless Min: 0 Max: 1 Default value: 1
The proportion of bites, when nets are in use, for which the net has any action whatsoever on the mosquito.
At the moment this is constant across humans and deterministic: relative attractiveness and survival factors are base*(1-usagepropActing) + intervention_factorusage*propActing.
See also "usage" (proportion of time nets are used by humans).
→ scenario → interventions → human → component → ITN → anophelesParams → deterrency
<deterrency
holeFactor=double
interactionFactor=double
holeScalingFactor=double
/>Effect of net on attractiveness of humans to mosquitoes relative to an unprotected adult human. Parameterisations should take into account that mosquitoes do not always bite indoors.
Attractiveness of the human is multiplied by exp(log(H)×h + log(P)×p + log(I)×h×p where H, P and I are the hole, insecticide and interaction factors respectively, h=exp(-holeIndex×holeScalingFactor) and p=1−exp(-insecticideContent×insecticideScalingFactor).
holeFactor=doubleUnits: none Max: 1
Value expected to be at least 0. Negative values are not necessarily invalid, but allow nets to increase transmission.
interactionFactor=doubleUnits: none Max: 1
holeFactor + insecticideFactor + interactionFactor must not be greater than 1, and is expected to be at least 0. A negative value is not necessarily invalid, but allows nets to increase transmission.
holeScalingFactor=doubleUnits: none Min: 0
→ scenario → interventions → human → component → ITN → anophelesParams → twoStageDeterrency
<twoStageDeterrency>
IN ANY ORDER:
| <entering ... />
| <attacking ... />
</twoStageDeterrency>Effect of net on attractiveness of humans to mosquitoes relative to an unprotected adult human. Parameterisations should take into account that mosquitoes do not always bite indoors.
This deterrency model multiplies human attractiveness by pEnt×pAtt divided by a base factor to normalise the output to 1 when there are no nets.
→ scenario → interventions → human → component → ITN → anophelesParams → twoStageDeterrency → entering
<entering
insecticideFactor=double
insecticideScalingFactor=double
/>pEnt represents the relative probability of entering due to ITNs: pEnt = exp(log(P)×p) where P is the insecticide factor and p=1−exp(-insecticideContent×insecticideScalingFactor).
insecticideFactor=doubleUnits: none Max: 1
Value expected to be at least 0. Negative values are not necessarily invalid, but allow nets to increase transmission.
insecticideScalingFactor=doubleUnits: none Min: 0
→ scenario → interventions → human → component → ITN → anophelesParams → twoStageDeterrency → attacking
<attacking
baseFactor=double
/>pAtt represents the relative probability of attacking a human after entering a house due to ITNs (i.e. of feeding/dying vs. flying off): pAtt = B + H×h + P×p + I×h×p where B is the base (without net) probability; H, P and I are the hole, insecticide and interaction factors respectively, h=exp(-holeIndex×holeScalingFactor) and p=1−exp(-insecticideContent×insecticideScalingFactor).
baseFactor=doubleUnits: dimensionless
→ scenario → interventions → human → component → ITN → anophelesParams → preprandialKillingEffect
<preprandialKillingEffect
baseFactor=double
/>Effect of net on survival mosquitoes as they seek to bite a human after choosing that human, relative to the same person not sleeping under a net. Parameterisations should take into account that mosquitoes do not always bite indoors.
Killing proportion is calculated as K = B + H×h + P×p + I×h×p where B is the base (without net) probability of death, H, P and I are the hole, insecticide and interaction factors respectively, h=exp(-holeIndex×holeScalingFactor) and p=1−exp(-insecticideContent×insecticideScalingFactor).
Survival of mosquitoes is adjusted via multiplication by (1−K) / (1−B). To keep this in the range [0,1], we require that B+H ≤ 1, B+P ≤ 1, B+H+P+I ≤ 1, H ≥ 0, P ≥ 0 and H+P+I ≥ 0.
baseFactor=doubleUnits: dimensionless
→ scenario → interventions → human → component → ITN → anophelesParams → postprandialKillingEffect
<postprandialKillingEffect
baseFactor=double
/>Effect of net on survival mosquitoes as they seek to escape from a human host and rest after a blood meal, relative to the same person not sleeping under a net. Parameterisations should take into account that mosquitoes do not always bite indoors.
Killing proportion is calculated as K = B + H×h + P×p + I×h×p where B is the base (without net) probability of death, H, P and I are the hole, insecticide and interaction factors respectively, h=exp(-holeIndex×holeScalingFactor) and p=1−exp(-insecticideContent×insecticideScalingFactor).
Survival of mosquitoes is adjusted via multiplication by (1−K) / (1−B). To keep this in the range [0,1], we require that B+H ≤ 1, B+P ≤ 1, B+H+P+I ≤ 1, H ≥ 0, P ≥ 0 and H+P+I ≥ 0.
baseFactor=doubleUnits: dimensionless
→ scenario → interventions → human → component → IRS
<IRS>
IN THIS ORDER:
| [ <usage ... /> ]
| <initialInsecticide ... />
| <insecticideDecay ... />
| ( <anophelesParams ... /> )+
</IRS>Description of indoor residual spraying interventions.
Description of effect for the more complex and probably more realistic Briet model: IRS has three effects, whos strength is calculated as a function of surviving insecticide content.
→ scenario → interventions → human → component → IRS → usage
<usage
value=double
/>Usage of Indoor residual spraying (IRS) interventions, from 0 to 1.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → IRS → initialInsecticide
<initialInsecticide
mu=double
sigma=double
/>The insecticide concentration of IRS (at time of spraying) is Gaussian distributed with mean "mu" and a standard deviation "sigma". The standard deviation should be small relative to the mean to avoid negative initial concentration. Any negative values sampled are set to 0.
Parameters of a normal distribution.
Variates are sampled as: X ~ N( mu, sigma² ).
mu=doubleUnits: (same as base units)
The mean of the normal distribution.
sigma=doubleUnits: (same as base units)
The standard deviation of variates.
→ scenario → interventions → human → component → IRS → insecticideDecay
<insecticideDecay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Decay curve for insecticide content of IRS. Documentation: see DecayFunction type or https://github.com/SwissTPH/openmalaria/wiki/ModelDecayFunctions
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → human → component → IRS → anophelesParams
<anophelesParams
mosquito=string
[ propActive=double ] DEFAULT VALUE 1
>
IN THIS ORDER:
| <deterrency ... />
| <preprandialKillingEffect ... />
| <postprandialKillingEffect ... />
</anophelesParams>mosquito=stringName of the affected anopheles-mosquito species.
propActive=doubleUnits: dimensionless Min: 0 Max: 1 Default value: 1
The proportion of bites for which the IRS has any action whatsoever on the mosquito.
At the moment this is constant across humans and deterministic: relative attractiveness and survival factors are base*(1-propActing) + intervention_factor*propActing.
→ scenario → interventions → human → component → IRS → anophelesParams → deterrency
<deterrency
insecticideFactor=double
insecticideScalingFactor=double
/>Effect of IRS on attractiveness of humans to mosquitoes relative to an unprotected adult human. Parameterisations should take into account that mosquitoes do not always bite indoors.
Attractiveness of the human is multiplied by exp(P×log(p)) where P is the insecticide factor, p=1−exp(-insecticideContent×insecticideScalingFactor).
insecticideFactor=doubleUnits: none Max: 1
Value expected to be at least 0. Negative values are not necessarily invalid, but allow nets to increase transmission.
insecticideScalingFactor=doubleUnits: none Min: 0
→ scenario → interventions → human → component → IRS → anophelesParams → preprandialKillingEffect
<preprandialKillingEffect
baseFactor=double
/>Effect of IRS on survival mosquitoes as they seek to bite a human after choosing that human, relative to the same person not protected by IRS. Parameterisations should take into account that mosquitoes do not always bite indoors. This parameter has been added since some data shows IRS to have a preprandial killing effect.
Killing proportion is calculated as K = B + P×p where B is the base (without protection) probability of death, and P is the insecticide factor, p=1−exp(-insecticideContent×insecticideScalingFactor).
Survival of mosquitoes is adjusted via multiplication by (1−K) / (1−B). To keep this in the range [0,1], we require that B+P ≤ 1 and P ≥ 0.
baseFactor=doubleUnits: dimensionless
→ scenario → interventions → human → component → IRS → anophelesParams → postprandialKillingEffect
<postprandialKillingEffect
baseFactor=double
/>Effect of IRS on survival mosquitoes as they seek to escape from a human host and rest after a blood meal, relative to the same person not protected by IRS. Parameterisations should take into account that mosquitoes do not always bite indoors.
Killing proportion is calculated as K = B + P×p where B is the base (without protection) probability of death, and P is the insecticide factor, p=1−exp(-insecticideContent×insecticideScalingFactor).
Survival of mosquitoes is adjusted via multiplication by (1−K) / (1−B). To keep this in the range [0,1], we require that B+P ≤ 1 and P ≥ 0.
baseFactor=doubleUnits: dimensionless
→ scenario → interventions → human → component → GVI
<GVI>
IN THIS ORDER:
| [ <usage ... /> ]
| <decay ... />
| ( <anophelesParams ... /> )+
</GVI>Low-level description of intervention effects on vectors (i.e. mosquitoes). Can be used to describe simple ITN or IRS interventions (though more complex models are available for these interventions) or other interventions such as mosquito repellant or ivermectin.
Note that all actions of this intervention component will decay according to a single decay function. If independant decay is wanted, a separate component can be used for each action.
→ scenario → interventions → human → component → GVI → usage
<usage
value=double
/>Usage of Generic vector interventions, from 0 to 1.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → GVI → decay
<decay
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")
[ L=string ]
[ k=double ] DEFAULT VALUE 1.0
[ mu=double ] DEFAULT VALUE 0
[ sigma=double ] DEFAULT VALUE 0
/>Description of decay of all intervention effects. Documentation: see DecayFunction type or https://github.com/SwissTPH/openmalaria/wiki/ModelDecayFunctions
Specification of decay or survival of a parameter.
function=("constant" or "step" or "linear" or "exponential" or "weibull" or "hill" or "smooth-compact")Units: None Min: 0 Max: 1
Determines which decay function to use. Available decay functions, for age t in years:
constant: 1
step: 1 for t less than L, otherwise 0
linear: 1 - t/L for t less than L, otherwise 0
exponential: exp( - t/L * log(2) )
weibull: exp( -(t/L)^k * log(2) )
hill: 1 / (1 + (t/L)^k)
smooth-compact: exp( k - k / (1 - (t/L)^2) ) for t less than L, otherwise 0
L=stringUnits: User-defined (defaults to years) Min: 0
(Time) scale parameter of distribution: this is either the age of complete decay (smooth-compact, step and linear functions) or the age at which the parameter has decayed to half its original value (exponential, weibull and hill). Not used when function="constant" (i.e. no decay).
This value can be specified in years, days or steps (e.g. 2y, 180d or 100t). When the unit is not specified years are assumed. The value is used without rounding except when sampling an age of decay, when the rounding happens as late as possible.
k=doubleUnits: none Min: 0 Default value: 1.0
Shape parameter of distribution. If not specified, default value of 1 is used. Meaning depends on function; not used in some cases.
mu=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
Note that with m=0, the median of the variable and the median value of L is unchanged, and thus the time at which the median decay amongst the population of decaying objects reaches half (assuming exponential, Weibull or Hill decay) is L. With m=-½σ² (negative half sigma squared) the mean of the variable will be 1 and mean of the half-life L, but the time at which mean decay of the population has reached half may not be L.
sigma=doubleMin: 0 Default value: 0
If sigma is non-zero, heterogeneity of decay is introduced via a random variable sampled from the log-normal distribution with mu and sigma as specified. Both mu and sigma default to zero when not specified.
The decay rate is multiplied by this variable (effectively, the half-life is divided by it).
→ scenario → interventions → human → component → GVI → anophelesParams
<anophelesParams
mosquito=string
[ propActive=double ] DEFAULT VALUE 1
>
IN THIS ORDER:
| [ <deterrency ... /> ]
| [ <preprandialKillingEffect ... /> ]
| [ <postprandialKillingEffect ... /> ]
</anophelesParams>mosquito=stringName of the affected anopheles-mosquito species.
propActive=doubleUnits: dimensionless Min: 0 Max: 1 Default value: 1
The proportion of bites for which the IRS has any action whatsoever on the mosquito.
At the moment this is constant across humans and deterministic: relative attractiveness and survival factors are base*(1-propActing) + intervention_factor*propActing.
→ scenario → interventions → human → component → GVI → anophelesParams → deterrency
<deterrency
value=double
/>Effect of IRS on attractiveness of humans to mosquitoes relative to an unprotected adult human. Parameterisations should take into account that mosquitoes do not always bite indoors.
Attractiveness of the human is multiplied this factor times survival of effect.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → GVI → anophelesParams → preprandialKillingEffect
<preprandialKillingEffect
value=double
/>Effect of IRS on survival mosquitoes as they seek to bite a human after choosing that human, relative to the same person not protected by IRS. Parameterisations should take into account that mosquitoes do not always bite indoors. This parameter has been added since some data shows IRS to have a preprandial killing effect.
Killing proportion is this factor multiplied by survival of effect.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → GVI → anophelesParams → postprandialKillingEffect
<postprandialKillingEffect
value=double
/>Effect of IRS on survival mosquitoes as they seek to escape from a human host and rest after a blood meal, relative to the same person not protected by IRS. Parameterisations should take into account that mosquitoes do not always bite indoors.
Killing proportion is this factor multiplied by survival of effect.
value=doubleA double-precision floating-point value.
→ scenario → interventions → human → component → recruitmentOnly
<recruitmentOnly/>Recruitment of a host into a sub-population.
All human-targeting intervention deployments recruit simulated humans into a sub-population which can be used for the purposes of cumulative deployment, deployment only to a sub-population and defining a cohort. This pseudo-intervention can be used to define a sub-population without also deploying some intervention.
→ scenario → interventions → human → component → clearImmunity
<clearImmunity/>Removes all exposure-related immunitsy gained over time by hosts without removing infections (or affecting the ability to gain immunity through exposure).
Hypothetical, but potentially useful to simulate scenarios with unprotected humans.
→ scenario → interventions → human → component → subPopRemoval
<subPopRemoval
[ onFirstBout=boolean ] DEFAULT VALUE false
[ onFirstTreatment=boolean ] DEFAULT VALUE false
[ onFirstInfection=boolean ] DEFAULT VALUE false
[ afterYears=double ]
/>Each human intervention component corresponds to a sub-population: those who have received or are considered to be protected by the intervention component. Humans automatically become members of this sub-population when receiving an intervention component; this element controls how humans are removed from the sub-population.
ITN attrition also removes humans from sub-populations.
Note that sub-populations do not directly correspond to an intervention's effects: lack of effectiveness does not imply removal from the sub-population (except as explicitly configured here) and removal from the sub-population does not halt an intervention's effects.
Sub-populations may be used to define a cohort, to restrict deployment of other interventions and to use cumulative deployment mode. A sub- population may or may not correspond (roughly) to humans protected by some intervention.
onFirstBout=booleanDefault value: false
If true, remove individuals from the sub-population at the start of the first episode (start of a clinical bout) since they were recruited into the sub-population. This is intended for cohort studies which measure time to the first episode, using active case detection.
Reports delayed due to health-system memory are forced out when this occurs. Note that this can increase the number of uncomplicated cases reported across the entire population; for this reason reports are not forced on recruitment or most removal options.
This does not prevent re-recruitment in the case that recruitment settings could conceivably recruit the same individual twice.
onFirstTreatment=booleanDefault value: false
If true, remove individuals from the sub-population when they first seektreatment since they were recruited into the sub-population. This is intended for cohort studies which measure the time to first episode, using passive case detection.
Reports delayed due to health-system memory are forced out when this occurs. Note that this can increase the number of uncomplicated cases reported across the entire population; for this reason reports are not forced on recruitment or most removal options.
This does not prevent re-recruitment in the case that recruitment settings could conceivably recruit the same individual twice.
onFirstInfection=booleanDefault value: false
If true, remove individuals from the sub-population at completion of the first survey in which they present with a patent infection since they were recruited into the sub-population. This intended for cohort studies which measure time to the first infection, using active case detection.
Reports delayed due to health-system memory are forced out when this occurs. Note that this can increase the number of uncomplicated cases reported across the entire population; for this reason reports are not forced on recruitment or most removal options.
This does not prevent re-recruitment in the case that recruitment settings could conceivably recruit the same individual twice.
afterYears=doubleUnits: Years Min: 0
If given, membership to the sub-population of humans who have received this intervention component expires after the given number of years. Note that future deployments renew membership (e.g. if this parameter is 4 years and the intervention is redeployed 3 years from now, expiry happens after 7 years).
This provides a crude way of modelling a cohort protected by some intervention. A few interventions provide more detailed ways of modelling expiry of protection. In any case, "expiry of protection" is an abstract concept and does not imply that all protection has ceased, even in the simulator.
This may also be useful for cumulative deployment.
Minimum duration is zero, which implies the human is effectively never a member of the sub-population; a duration of one timestep implies the human is a member of the sub-population while any futher interventions are deployed on the same time as this human becomes a member and on the next update of the human (including transmission and health system events) but not beyond that. If this attribute is not given, the simulated human is a member until death or some other option triggers removal.
Input is rounded to the nearest time step.
→ scenario → interventions → human → deployment
<deployment
[ name=string ]
>
IN THIS ORDER:
| ( <component ... /> )+
| ( <condition ... /> )*
| ( <continuous ... /> )*
| ( <timed ... /> )*
</deployment>This element describes deployment of an intervention: which components are deployed, how humans are selected for deployment (via timed or age-based deployment) as well as a few additional restrictions (e.g. vaccine dosing restrictions).
All components deployed by this intervention are deployed to the same people (each timed or continuous deployment selects recipients and then gives each recipient all components of the intervention).
name=stringName of intervention
→ scenario → interventions → human → deployment → component
<component
id=string
/>The list of components deployed to eligible humans.
id=stringThe identifier (short name) of a component.
→ scenario → interventions → human → deployment → condition
<condition
measure=string
[ minValue=double ]
[ maxValue=double ]
initialState=boolean
/>If conditions are specified, deployment of this intervention will only go ahead if all specified conditions are true. Condition statements are evaluated only during surveys, so deployment is enabled or disabled depending on the results of the most recent survey. So called unreported surveys can be used to reevaluate conditions without increasing granularity of output.
Conditions are evaluated for the whole population, not for individual age-groups or cohorts.
This affects all types of deployment.
measure=stringThe monitoring measure to test. Not all measures are available for use.
minValue=doubleMinimum value. If specified, the measured variable must be greater than this value for the condition to be satisfied.
maxValue=doubleMaximum value. If specified, the measured variable must be less than this value for the condition to be satisfied.
initialState=booleanWhether this condition is considered true or false before updated by a survey.
→ scenario → interventions → human → deployment → continuous
<continuous>
IN THIS ORDER:
| [ <restrictToSubPop ... /> ]
| ( <deploy ... /> )+
</continuous>List of ages at which deployment takes place (through EPI, post-natal and school-based programmes, etc.).
A sub-population restriction may be added as a property of the list of continuous deployments.
→ scenario → interventions → human → deployment → continuous → restrictToSubPop
<restrictToSubPop
id=string
[ complement=boolean ] DEFAULT VALUE false
/>If this element is specified, deployment is restricted to some sub-population (specified via the "id" attribute); otherwise the target population is the entire simulated population. Either way, other deployment restrictions (age, time, number of vaccine doeses) still apply.
id=stringThe identifier (short name) of the sub-population (i.e. the "id" of some intervention component). Also see the "complement" attribute.
complement=booleanDefault value: false
If this is not specified or is false, deployment is restricted to the sub-population of people protected by the intervention component who's id is given. If complement is set to true, deployment is instead restricted to the complement of that sub-population, i.e. to those
→ scenario → interventions → human → deployment → continuous → deploy
<deploy
targetAgeYrs=double
[ begin=string ]
[ end=string ]
/>targetAgeYrs=doubleUnits: Years Min: 0 Max: 100
Target age of intervention.
Input is rounded to the nearest time step.
begin=stringUnits: User defined (defauls to steps)
First time at which this deployment is active. If not specified, deployment starts at the beginning of the intervention period.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
end=stringUnits: User defined (defauls to steps)
End of the period during which the intervention is active (to be exact, the first step of the intervention period at which the item becomes inactive). If not specified, deployment never ceases after starting during the simulation.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
→ scenario → interventions → human → deployment → timed
<timed>
IN THIS ORDER:
| [ <restrictToSubPop ... /> ]
| [ <cumulativeCoverage ... /> ]
| ( <deploy ... /> )+
</timed>List of timed deployments of the intervention (that is, of deployment campaigns).
Cumulative deployment mode can be specified for all deployments in a timed list. To allow multiple cumulative deployment descriptions, the entire timed list may be repeated.
→ scenario → interventions → human → deployment → timed → restrictToSubPop
<restrictToSubPop
id=string
[ complement=boolean ] DEFAULT VALUE false
/>If this element is specified, deployment is restricted to some sub-population (specified via the "id" attribute); otherwise the target population is the entire simulated population. Either way, other deployment restrictions (age, time, number of vaccine doeses) still apply.
id=stringThe identifier (short name) of the sub-population (i.e. the "id" of some intervention component). Also see the "complement" attribute.
complement=booleanDefault value: false
If this is not specified or is false, deployment is restricted to the sub-population of people protected by the intervention component who's id is given. If complement is set to true, deployment is instead restricted to the complement of that sub-population, i.e. to those
→ scenario → interventions → human → deployment → timed → cumulativeCoverage
<cumulativeCoverage
component=string
/>If this element is not specified, standard deployment occurs, where a portion of the population as given by the coverage property of this campaign is selected, and interventions are deployed to all of these people (regardless of previous coverage).
If this attribute is specified, instead, the population is divided into two sets: those who are a member of a certain sub-population and those who are not (see "subPopRemoval" element). If the proportion of people in the first set is less than the desired coverage, then the proportion of people from the second set needed to increase total coverage to the desired coverage is calculated. This proportion is then used as the probablity of selection from the second set into a third set of people who then receive all interventions deployed by this campaign.
Note that selection is stochastic so the final coverage level may not be exactly that desired. Note also that the component used when selecting people need not actually be one of the components deployed by this intervention, although that is the intended use case.
component=stringThe identifier (short name) of the component used when selecting people.
→ scenario → interventions → human → deployment → timed → deploy
<deploy
time=string
[ maxAge=double ]
[ minAge=double ] DEFAULT VALUE 0
[ repeatStep=string ]
[ repeatEnd=string ]
/>time=stringUnits: User defined (defauls to steps) Min: 0
Time at which this deployment occurs.
See doc on intervention period and on monitoring/startDate for details of how times work. Can be specified in steps, days, years, or as a date (examples: 15t, 75d, 0.2y, 2000-03-16).
maxAge=doubleUnits: Years Min: 0
Maximum age of eligible individuals (defaults to no limit).
Input is rounded to the nearest time step.
minAge=doubleUnits: Years Min: 0 Default value: 0
Minimum age of eligible individuals (defaults to 0).
Input is rounded to the nearest time step.
repeatStep=stringUnits: User defined
See repeatEnd's documentation.
repeatEnd=stringUnits: User defined
Either both repeatStep and repeatEnd should be present or neither. If present, the deployment is repeated every repeatStep timesteps (i.e. if t0 is the initial time and x is repeatStep, depolyments are done at times t0, t0+x, t0+2*x, ...), ending before repeatEnd (final repetition is the one before repeatEnd).
Note that repeatEnd may be specified as a date but repeatStep must be a duration (days, steps or years).
→ scenario → healthSystem
<healthSystem>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <EventScheduler ... />
| | <ImmediateOutcomes ... />
| | <DecisionTree5Day ... />
| <CFR ... />
| <pSequelaeInpatient ... />
</healthSystem>Description of health system.
Description of case management system, used to specify the initial model or a replacement (an intervention). Encompasses case management data and some other data required to derive case outcomes.
Contains a sub-element describing the particular health-system in use. Health system data is here defined as data used to decide on a treatment strategy, given a case requiring treatment.
→ scenario → entomology
<entomology
name=string
mode=("forced" or "dynamic")
[ scaledAnnualEIR=double ]
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <nonVector ... />
| | <vector ... />
</entomology>Description of entomological data
name=stringName of entomology data
mode=("forced" or "dynamic")Transmission simulation mode: may be forced (in which case interventions and changes to human infectiousness cannot affect EIR) or dynamic (in which the above can affect EIR). The full vector model is only used in dynamic mode. This can not be changed by interventions, except for the changeEIR intervention for the non-vector model which replaces the EIR with a new description (used in forced mode).
scaledAnnualEIR=doubleUnits: Infectious bites per adult per year
If set, the annual EIR (for all species of vector) is scaled to this level; can be omitted if not needed.
→ scenario → entomology → nonVector
<nonVector
eipDuration=int
>
IN THIS ORDER:
| ( <EIRDaily ... /> )+
</nonVector>Description of transmission setting for models without vector control interventions (included for backward compatibility)
eipDuration=intUnits: Days
The duration of sporogony in days
→ scenario → entomology → vector
<vector>
IN THIS ORDER:
| ( <anopheles ... /> )+
| ( <nonHumanHosts ... /> )*
</vector>Parameters of the transmission model
→ scenario → entomology → vector → anopheles
<anopheles
mosquito=string
propInfected=double
propInfectious=double
>
IN THIS ORDER:
| <seasonality ... />
| <mosq ... />
| [ <lifeCycle ... /> ]
| [ <simpleMPD ... /> ]
| ( <nonHumanHosts ... /> )*
</anopheles>Description of input EIR for one specific vector species in terms of a Fourier approximation to the ln of the EIR during the burn in period
mosquito=stringIdentifier for this anopheles species
propInfected=doubleUnits: Proportion Min: 0 Max: 1
Initial guess of the proportion of mosquitoes which are infected, o: O_v(t) = o*N_v(t). Only used as a starting value.
propInfectious=doubleUnits: Proportion Min: 0 Max: 1
Initial estimate of the proportion of mosquitoes which are infectious, s: S_v(t) = s*N_v(t). Used as a starting value and then fit.
→ scenario → entomology → vector → anopheles → seasonality
<seasonality
input=("EIR")
[ annualEIR=double ]
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <fourierSeries ... />
| | <monthlyValues ... />
| | <dailyValues ... />
</seasonality>Specifies the seasonality of transmission and optionally the level of annual transmission.
input=("EIR")Specify what seasonality measure is given.
At the moment, only EIR is supported, but in the future, all the below should be supported.
EIR: seasonality of entomological inoculations is input. Units: entomological inoculations per adult per annum.
hostSeeking: seasonality of densities of flying host-seeking mosquitoes is input (in the model this is notated N_v). Units: mosquitoes.
emergence: seasonality of emergence pupa into adults. Units: mosquitoes.
larvalResources: seasonality of larval resources. Units: X.
annualEIR=doubleUnits: Inoculations per adult per annum Min: 0
If this attribute is included, EIR for this species is scaled to this level. Note that if the scaledAnnualEIR attribute of the entomology element is also used, EIR is scaled again, making this attribute the EIR relative to other species.
With some seasonality inputs, this attribute is optional, in which case (if scaledAnnualEIR is also not specified) transmission depends on all parameters of the vector. With some seasonality inputs, however, this parameter must be specified.
→ scenario → entomology → vector → anopheles → seasonality → fourierSeries
<fourierSeries
EIRRotateAngle=double
>
IN THIS ORDER:
| ( <coeffic ... /> )*
</fourierSeries>Seasonality is reproduced from the exponential of a fourier series specified by the following coefficients. Note that the a0 term is not needed; the annualEIR attribute of the seasonality element should be used to scale EIR instead.
EIRRotateAngle=doubleUnits: Radians
Rotation angle defining the origin of the Fourier approximation to ln (EIR)
→ scenario → entomology → vector → anopheles → seasonality → fourierSeries → coeffic
<coeffic
a=double
b=double
/>A pair of Fourier series coefficients. The first element specifies a1 and b1, the second a2 and b2, etc. Any number (from 0 up) of pairs may be given.
a=doublea_n parameter of Fourier approximation to ln(EIR) for some natural number n.
b=doubleb_n parameter of Fourier approximation to ln(EIR) for some natural number n.
→ scenario → entomology → vector → anopheles → seasonality → monthlyValues
<monthlyValues
smoothing=("none" or "fourier")
>
IN THIS ORDER:
| ( <value ... /> ){12,12}
</monthlyValues>Description of seasonality from monthly values. Multiple smoothing methods are possible (see smoothing attribute).
List should contain twelve entries: January to December.
smoothing=("none" or "fourier")How the monthly values are converted into a daily sequence of values:
-
none: no smoothing (step function)
-
Fourier: a Fourier series (with terms up to a2/b2) is fit to the sequence of monthly values and used to generate a smoothed list of daily values.
→ scenario → entomology → vector → anopheles → seasonality → monthlyValues → value
<value>
double
</value>Monthly value
→ scenario → entomology → vector → anopheles → seasonality → dailyValues
<dailyValues>
IN THIS ORDER:
| ( <value ... /> ){365,365}
</dailyValues>Description of seasonality from daily values.
List should contain 365 entries: 1st January to 31st December.
→ scenario → entomology → vector → anopheles → seasonality → dailyValues → value
<value>
double
</value>Daily value
→ scenario → entomology → vector → anopheles → mosq
<mosq
minInfectedThreshold=double
>
IN ANY ORDER:
| <mosqRestDuration ... />
| <extrinsicIncubationPeriod ... />
| <mosqLaidEggsSameDayProportion ... />
| <mosqSeekingDuration ... />
| <mosqSurvivalFeedingCycleProbability ... />
| <availabilityVariance ... />
| <mosqProbBiting ... />
| <mosqProbFindRestSite ... />
| <mosqProbResting ... />
| <mosqProbOvipositing ... />
| <mosqHumanBloodIndex ... />
</mosq>- mosqRestDuration
- extrinsicIncubationPeriod
- mosqLaidEggsSameDayProportion
- mosqSeekingDuration
- mosqSurvivalFeedingCycleProbability
- availabilityVariance
- mosqProbBiting
- mosqProbFindRestSite
- mosqProbResting
- mosqProbOvipositing
- mosqHumanBloodIndex
Parameters describing the feeding cycle and human mosquito interaction of a single species of anopheles mosquito.
minInfectedThreshold=doubleMin: 0
If less than this many mosquitoes remain infected, transmission is interrupted.
→ scenario → entomology → vector → anopheles → mosq → mosqRestDuration
<mosqRestDuration
value=int
/>name:Duration of the resting period of the vector (days);
value=intAn integer value.
→ scenario → entomology → vector → anopheles → mosq → extrinsicIncubationPeriod
<extrinsicIncubationPeriod
value=int
/>name:Extrinsic incubation period (days)
value=intAn integer value.
→ scenario → entomology → vector → anopheles → mosq → mosqLaidEggsSameDayProportion
<mosqLaidEggsSameDayProportion
value=double
/>Proportion of mosquitoes host seeking on same day as ovipositing
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → mosq → mosqSeekingDuration
<mosqSeekingDuration
value=double
/>Duration of the host-seeking period of the vector (days)
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → mosq → mosqSurvivalFeedingCycleProbability
<mosqSurvivalFeedingCycleProbability
value=double
/>Probability that the mosquito survives the feeding cycle
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → mosq → availabilityVariance
<availabilityVariance
value=double
/>Variance in availability rate of humans to mosquitoes. The mean rate is calculated based on other parameters.
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → mosq → mosqProbBiting
<mosqProbBiting
mean=double
variance=double
/>Probability that the mosquito succesfully bites chosen host
Parameters of a normal distribution, provided as mean and variance.
Variates are sampled from Be(α,β) where α and β are determined from the mean and variance as follows: let v be the variance and c=mean/(1-mean). Then we set α=cβ and β=((c+1)²v - c)/((c+1)³v).
mean=doubleUnits: none
The mean of the beta distribution (must be in the open range (0,1)).
variance=doubleUnits: none
The standard deviation of variates.
→ scenario → entomology → vector → anopheles → mosq → mosqProbFindRestSite
<mosqProbFindRestSite
mean=double
variance=double
/>Probability that the mosquito escapes host and finds a resting place after biting
Parameters of a normal distribution, provided as mean and variance.
Variates are sampled from Be(α,β) where α and β are determined from the mean and variance as follows: let v be the variance and c=mean/(1-mean). Then we set α=cβ and β=((c+1)²v - c)/((c+1)³v).
mean=doubleUnits: none
The mean of the beta distribution (must be in the open range (0,1)).
variance=doubleUnits: none
The standard deviation of variates.
→ scenario → entomology → vector → anopheles → mosq → mosqProbResting
<mosqProbResting
mean=double
variance=double
/>Probability of mosquito successfully resting after finding a resting site
Parameters of a normal distribution, provided as mean and variance.
Variates are sampled from Be(α,β) where α and β are determined from the mean and variance as follows: let v be the variance and c=mean/(1-mean). Then we set α=cβ and β=((c+1)²v - c)/((c+1)³v).
mean=doubleUnits: none
The mean of the beta distribution (must be in the open range (0,1)).
variance=doubleUnits: none
The standard deviation of variates.
→ scenario → entomology → vector → anopheles → mosq → mosqProbOvipositing
<mosqProbOvipositing
value=double
/>Probability of a mosquito successfully laying eggs given that it has rested
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → mosq → mosqHumanBloodIndex
<mosqHumanBloodIndex
value=double
/>The proportion of resting mosquitoes which fed on human blood during the last feed.
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → lifeCycle
<lifeCycle
[ estimatedLarvalResources=double ] DEFAULT VALUE 1e8
>
IN ANY ORDER:
| <eggStage ... />
| <larvalStage ... />
| <pupalStage ... />
| <femaleEggsLaidByOviposit ... />
</lifeCycle>Parameters describing the life-cycle of this species of mosquito
estimatedLarvalResources=doubleUnits: X Default value: 1e8
An estimate of mean annual availability of resources to larvae. Used to get the resource usage fitting algorithm going; if the algorithm fails to fit the resource availability then tweaking this parameter may help. In other cases tweaking this parameter shouldn't be necessary.
Default value is 10⁸ (1e8). Units are arbitrary but must be the same as those used by the resourceUsage parameter.
→ scenario → entomology → vector → anopheles → lifeCycle → eggStage
<eggStage
duration=int
survival=double
/>Parameters for the egg stage of development
Parameters associated with a mosquito development stage.
duration=intUnits: Days
Duration of the stage (i.e. length of time mosquito is an egg/larva/pupa).
survival=doubleUnits: Proportion
Probability that mosquito survives this size (probability of egg hatching, a larva becoming a pupa or a pupa emerging as an adult, at the start of that stage).
→ scenario → entomology → vector → anopheles → lifeCycle → larvalStage
<larvalStage>
</larvalStage>Parameters for the larval stage of development
Parameters associated with a mosquito development stage.
→ scenario → entomology → vector → anopheles → lifeCycle → larvalStage → daily
<daily
resourceUsage=double
effectCompetition=double
/>List of parameters which apply during the larval stage of development. List length must equal stage duration, with first item corresponding to first 24 hours after hatching, second item to hours 24-48, and so on.
resourceUsage=doubleUnits: X
Resource usage during larval stage of development. Units are arbitrary.
effectCompetition=doubleUnits: none
Effect of competition over resources on development.
→ scenario → entomology → vector → anopheles → lifeCycle → pupalStage
<pupalStage
duration=int
survival=double
/>Parameters for the pupal stage of development
Parameters associated with a mosquito development stage.
duration=intUnits: Days
Duration of the stage (i.e. length of time mosquito is an egg/larva/pupa).
survival=doubleUnits: Proportion
Probability that mosquito survives this size (probability of egg hatching, a larva becoming a pupa or a pupa emerging as an adult, at the start of that stage).
→ scenario → entomology → vector → anopheles → lifeCycle → femaleEggsLaidByOviposit
<femaleEggsLaidByOviposit
value=double
/>The total number of female eggs laid by a female mosquito at the conclusion to a feeding cycle.
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → simpleMPD
<simpleMPD>
IN ANY ORDER:
| <developmentDuration ... />
| <developmentSurvival ... />
| <femaleEggsLaidByOviposit ... />
</simpleMPD>Parameters describing the simple mosquito population dynamics model.
This is a simpler version of the life-cycle model, requiring less parameters and with much simpler initialisation.
→ scenario → entomology → vector → anopheles → simpleMPD → developmentDuration
<developmentDuration
value=int
/>Duration from egg laying to emergence in days.
value=intAn integer value.
→ scenario → entomology → vector → anopheles → simpleMPD → developmentSurvival
<developmentSurvival
value=double
/>Probability that mosquito survives from the egg being laid to emergence, given no resouce limitations (no density constraints).
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → simpleMPD → femaleEggsLaidByOviposit
<femaleEggsLaidByOviposit
value=double
/>The total number of female eggs laid by a female mosquito at the conclusion to a feeding cycle.
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → nonHumanHosts
<nonHumanHosts
name=string
>
IN ANY ORDER:
| <mosqRelativeEntoAvailability ... />
| <mosqProbBiting ... />
| <mosqProbFindRestSite ... />
| <mosqProbResting ... />
</nonHumanHosts>Non human host parameters, per type of host (must match up with non-species-specific parameters).
name=stringIdentifier for this category of non-human hosts
→ scenario → entomology → vector → anopheles → nonHumanHosts → mosqRelativeEntoAvailability
<mosqRelativeEntoAvailability
value=double
/>Relative availability of non-human hosts of type i to other non-human hosts; the sum of this across all non-human hosts must be 1.
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → nonHumanHosts → mosqProbBiting
<mosqProbBiting
value=double
/>Probability of mosquito successfully biting host
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → nonHumanHosts → mosqProbFindRestSite
<mosqProbFindRestSite
value=double
/>Probability that the mosquito escapes host and finds a resting place after biting
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → anopheles → nonHumanHosts → mosqProbResting
<mosqProbResting
value=double
/>Probability of mosquito successfully resting after finding a resting site
value=doubleA double-precision floating-point value.
→ scenario → entomology → vector → nonHumanHosts
<nonHumanHosts
name=string
number=double
/>name=stringName of this species of non human hosts (must match up with those described per anopheles section).
number=doubleUnits: Number
Population size of this non-human host.
<parasiteGenetics
samplingMode=("initial" or "tracking")
>
IN THIS ORDER:
| ( <locus ... /> )+
</parasiteGenetics>A specification of genotypes of infection parasites.
May be omitted; in this case there is no modelling of genetic differences of infections (resistance, fitness).
samplingMode=("initial" or "tracking")This controls how genotypes are determined for new infections during the intervention period. Prior to this (in initialisation phases), genotypes are always sampled using the specified initial frequencies.
Mode "initial" continues to sample genotypes using initial frequencies (i.e. independent of the success of parent generations of parasites).
Mode "tracking" samples genotypes based on the success parent generations of parasites have in infecting mosquitoes, tracked per genotype.
It is possible that in the future a recombination option will be added to this list, however designing a suitable model is not trivial.
→ scenario → parasiteGenetics → locus
<locus
name=string
>
IN THIS ORDER:
| ( <allele ... /> )+
</locus>Describes a locus, or a point at which an infection may vary. The genotype of an infection is determined by choosing one allele at each locus. Initial frequencies of alleles are specified independently for each locus, but subsequent infections are selected according to success of genotypes.
Alleles at loci can affect fitness and resistance to any number of drugs.
name=stringName of the Locus
→ scenario → parasiteGenetics → locus → allele
<allele
name=string
initialFrequency=double
fitness=double
/>Describes an allele, or one possible genetic option of multiple at one point of variance.
name=stringName of the allele; used to refer to it elsewhere.
initialFrequency=doubleSpecification of how commonly this allele occurs during warmup relative to other alleles of the same locus.
During the simulation's initialisation phases, the frequency at which each allele of each locus occurs is fixed. After the initialisation phase, frequency of alleles is modelled as an emergent property of the success of genotypes.
fitness=doubleFitness factor of the allele. This is multiplication factor used to speed up or slow down replication of parasites.
For example, if a genotype has an allele with a fitness factor of 1 at one locus and another allele with a fitness factor of 0.8 at a second locus, then the parasites with the genotype will replicate 20% slower than the baseline.
→ scenario → pharmacology
<pharmacology>
IN THIS ORDER:
| <treatments ... />
| <drugs ... />
</pharmacology>Drug model parameters and drug usage parameters
A library of drug related data for the PK/PD model.
→ scenario → pharmacology → treatments
<treatments>
IN THIS ORDER:
| ( <schedule ... /> )+
| ( <dosages ... /> )+
</treatments>A library of drug deployment schedules and dosages.
→ scenario → pharmacology → treatments → schedule
<schedule
name=string
>
IN THIS ORDER:
| ( <medicate ... /> )*
</schedule>A schedule for the administration of drugs in a course of treatment.
Note that dose sizes are multiplied by some multiplier (see dosages) and the times of all doses may be delayed.
name=stringName for referring to this deployment schedule
→ scenario → pharmacology → treatments → schedule → medicate
<medicate
drug=string
mg=double
hour=double
/>drug=stringAbbreviated name of drug compound
mg=doubleUnits: mg per something
Quantity of drug compound in mg per something. A separate dosage table must be used when medicating, which may specify multipliers of this number based on patient age or weight.
hour=doubleUnits: Hours Min: 0
Number of hours past start of timestep this drug dose is administered at (first dose should be at hour 0).
→ scenario → pharmacology → treatments → dosages
<dosages
name=string
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | ( <age ... /> )+
| | ( <bodymass ... /> )+
| | <multiply ... />
</dosages>A table for selecting a dose size given an age.
Categories must uniquely cover all ages from birth, with no upper bound. Categories must be listed in order of age, increasing; the first must have lower bound 0. Upper bounds are equal to the lower bound of the next category, (but are exclusive where lower bounds are inclusive); the last category has no upper bound.
name=stringName for referring to this dosage table
→ scenario → pharmacology → treatments → dosages → age
<age
lowerbound=double
dose_mult=double
/>Gives a dose multiplier for an age or body mass range.
lowerbound=doubleUnits: years Min: 0
dose_mult=doubleMin: 0
The dose size given in the schedule (in mg) is multiplied by this value for patients falling into this age range when this dosage table is used.
→ scenario → pharmacology → treatments → dosages → bodymass
<bodymass
lowerbound=double
dose_mult=double
/>Gives a dose multiplier for an age or body mass range.
lowerbound=doubleUnits: years Min: 0
dose_mult=doubleMin: 0
The dose size given in the schedule (in mg) is multiplied by this value for patients falling into this age range when this dosage table is used.
→ scenario → pharmacology → treatments → dosages → multiply
<multiply
by=("kg")
/>Multiply the dose by some quantity, such as patient weight.
by=("kg")Quantity to multiply the dose by. Only option is "kg" (patient weight in kg).
→ scenario → pharmacology → drugs
<drugs>
IN THIS ORDER:
| ( <drug ... /> )+
</drugs>A library of drug PK/PD data.
→ scenario → pharmacology → drugs → drug
<drug
abbrev=string
>
IN THIS ORDER:
| <PD ... />
| <PK ... />
</drug>A drug description with PK/PD parameters.
abbrev=string→ scenario → pharmacology → drugs → drug → PD
<PD
[ locus=string ]
>
IN THIS ORDER:
| ( <phenotype ... /> )+
</PD>locus=stringOptional; if present specifies the locus corresponding to this drug's PD phenotypes: each phenotype must then match one of that locus's alleles. Otherwise the drug should specify only one phenotype.
There is currently a one-to-many correspondance between loci and drugs.
→ scenario → pharmacology → drugs → drug → PD → phenotype
<phenotype
[ name=string ]
>
IN THIS ORDER:
| ( <restriction ... /> )*
| <max_killing_rate ... />
| <IC50 ... />
| <slope ... />
</phenotype>Pharmaco-Dynamic parameters for some resistance phenotype.
To model resistance to this drug, describe multiple infection phenotypes (with respect to these PD parameters) and list one or more "restrict" elements for each phenotype.
Loci are specified elsewhere. Multiple loci may influence the action of a single drug and each locus may influence multiple drugs.
name=stringName of the phenotype; for documentation use only.
→ scenario → pharmacology → drugs → drug → PD → phenotype → restriction
<restriction
onLocus=string
toAllele=string
/>Specifies the mapping from genotype to phenotype. For each drug type, if only one phenotype is present, restrictions need not be specified, but otherwise restrictions must be specified.
The set of loci affecting phenotypes of this drug's action must be fixed for any drug type. Each phenotype must list, for each of these loci, a restriction to one or more alleles under the locus.
onLocus=stringA locus under which only a restricted set of alleles map to this phenotype.
toAllele=stringOne allele of a locus upon which phenotype choice depends. If multiple alleles under this locus should map to the same phenotype, repeat the whole "restriction onLocus..." element.
→ scenario → pharmacology → drugs → drug → PD → phenotype → max_killing_rate
<max_killing_rate>
double
</max_killing_rate>k1 — Maximal parasite killing rate.
→ scenario → pharmacology → drugs → drug → PD → phenotype → IC50
<IC50
[ sigma=double ] DEFAULT VALUE 0
>
double
</IC50>Half maximal effect concentration. If sigma > 0, the IC50 is sampled for each infection from a log-normal distribution with mean of this value and the sigma value specified, i.e. X ~ log N( log(mean) - s^2 / 2, s^2 ) .
sigma=doubleDefault value: 0
Distribution parameter describing per-infection variation of IC50. If zero or not specified, the IC50 is not sampled. See documentation of parent element.
→ scenario → pharmacology → drugs → drug → PD → phenotype → slope
<slope>
double
</slope>n — Slope of the concentration effect curve
→ scenario → pharmacology → drugs → drug → PK
<PK>
IN THIS ORDER:
| <negligible_concentration ... />
| EXACTLY ONE OF:
| | <half_life ... />
| | IN THIS ORDER:
| | | <k ... />
| | | <m_exponent ... />
| [ <k_a ... /> ]
| [ <conversion ... /> ]
| <vol_dist ... />
| [ <compartment2 ... /> ]
| [ <compartment3 ... /> ]
</PK>→ scenario → pharmacology → drugs → drug → PK → negligible_concentration
<negligible_concentration>
double
</negligible_concentration>Concentration below which drug's effects are deemed negligible and can be removed from simulation.
→ scenario → pharmacology → drugs → drug → PK → half_life
<half_life>
double
</half_life>Used to calculate elimination rate λ, calculated as λ = ln(2) / half_life. The basic form of decay is C(t) = C0 * exp(-λ*t).
Alternatively, elimination rate can be specified via k and m_exponent.
→ scenario → pharmacology → drugs → drug → PK → k
<k
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Constant used to calculate the elimination rate λ, which is calculated as λ = k / (body_mass ^ m_exponent), where body_mass is the patient's weight in kg and m_exponent is the next parameter. The basic form of decay is C(t) = C0 * exp(-λ*t).
If sigma > 0, k is sampled per-human from the log-normal distribution: ln N( ln(mean) - σ^2 / 2, σ^2).
Alternatively, elimination rate can be specified via half_life.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → m_exponent
<m_exponent>
double
</m_exponent>Constant used to calculate the elimination rate λ, which is calculated as λ = k / (body_mass ^ m_exponent), where body_mass is the patient's weight in kg and k is the previous parameter. The basic form of decay is C(t) = C0 * exp(-λ*t).
Alternatively, elimination rate can be specified via half_life.
Note that in the case of a conversion model, this applies to both the elimination and the conversion rates.
→ scenario → pharmacology → drugs → drug → PK → k_a
<k_a
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Absorption rate parameter. Not allowed for one compartment models, but required for two and three compartment models and one compartment with conversion model (for the parent drug only).
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → conversion
<conversion>
IN ANY ORDER:
| <metabolite ... />
| <rate ... />
| <molRatio ... />
</conversion>Configures the parent drug in a conversion model.
To use a conversion model, the parent drug should have this section defined as well as half-life or k (direct elimination; this may be zero) and k_a (absorption rate; this may be large).
The metabolite drug should define half-life or k (elimination of metabolite), but not k_a (absorption rate) or this section (conversion). It is not possible for the metabolite to itself undergo conversion with the current models.
→ scenario → pharmacology → drugs → drug → PK → conversion → metabolite
<metabolite>
string
</metabolite>The abbreviation of the metabolite drug (e.g. "DHA" or "DHA_AR").
→ scenario → pharmacology → drugs → drug → PK → conversion → rate
<rate
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Rate of conversion of parent drug to metabolite.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → conversion → molRatio
<molRatio>
double
</molRatio>Ratio of molecular weights: molecular weight of the metabolite divided by molecular weight of the parent.
→ scenario → pharmacology → drugs → drug → PK → vol_dist
<vol_dist
[ sigma=double ] DEFAULT VALUE 0
>
double
</vol_dist>Volume of Distribution
sigma=doubleDefault value: 0
Distribution parameter describing per-human variation of volume of distribution. If zero or not specified, the parameter is not sampled. See documentation of parent element.
→ scenario → pharmacology → drugs → drug → PK → compartment2
<compartment2>
IN ANY ORDER:
| <a12 ... />
| <a21 ... />
</compartment2>Optional element specifying conversion parameters to- and from- a second compartment.
→ scenario → pharmacology → drugs → drug → PK → compartment2 → a12
<a12
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Absorption rate from the central compartment to the first periphery compartment (2). The parameter k12 = a12 / m where m is the body mass (kg).
It is sampled per-patient when sigma > 0.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → compartment2 → a21
<a21
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Absorption rate from the first periphery compartment (2) to the central compartment. The parameter k21 = a21 / m where m is the body mass (kg).
It is sampled per-patient when sigma > 0.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → compartment3
<compartment3>
IN ANY ORDER:
| <a13 ... />
| <a31 ... />
</compartment3>Optional element specifying conversion parameters to- and from- a third compartment.
→ scenario → pharmacology → drugs → drug → PK → compartment3 → a13
<a13
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Absorption rate from the central compartment to the second periphery compartment (3). The parameter k13 = a13 / m where m is the body mass (kg).
It is sampled per-patient when sigma > 0.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → pharmacology → drugs → drug → PK → compartment3 → a31
<a31
mean=double
[ cv=double ]
distr=("lnorm" or "const")
/>Absorption rate from the second periphery compartment (3) to the central compartment. The parameter k31 = a31 / m where m is the body mass (kg).
It is sampled per-patient when sigma > 0.
Parameters of some distribution. The mean is that provided and the standard deviation is cv*mean.
Log-normal: σ = cv * mean ; μ = ln(mean) - σ² / 2 ; X ~ ln N( μ, σ² ) ; equivalent R sample: rlnorm(1, log(mean) - ((cv * mean)^2) / 2, cv * mean).
mean=doubleUnits: (same as base units)
The mean of the distribution.
cv=doubleUnits: unitless
Coefficient of variance (mean * cv gives standard deviation).
Must be specified when distribution is not constant.
distr=("lnorm" or "const")Selects the distribution to use.
const: constant (no distribution). Setting cv=0 has the same behaviour.
lnorm: log-normal distribution
→ scenario → diagnostics
<diagnostics>
IN THIS ORDER:
| ( <diagnostic ... /> )*
</diagnostics>Diagnostic model parameters
→ scenario → diagnostics → diagnostic
<diagnostic
name=string
[ units=("Other" or "Garki" or "Malariatherapy") ]
>
IN THIS ORDER:
| EXACTLY ONE OF:
| | <deterministic ... />
| | <stochastic ... />
</diagnostic>name=stringName of this diagnostic (parameterisation). May be used elsewhere in the XML document to refer to this set of diagnostic parameters.
units=("Other" or "Garki" or "Malariatherapy")Parasite densities, as estimated according to standard microscopy methods, the Garki method, and as derived from Malariatherapy data are not equivalent. Internally, a "bias" factor is used to convert values estimated by one methods to values comparable with another (see AJTMHv75 supplement 2 pp20-21).
This option allows specification of which methodology the density given in the diagnostic specification is measured with. Values allowed are: Malariatherapy, Garki and Other. If not specified, Other is assumed, unless the GARKI_DENSITY_BIAS model option is used, in which case this option must be specified.
→ scenario → diagnostics → diagnostic → deterministic
<deterministic
minDensity=double
/>Specify that an artificial deterministic test is used: outcome is positive if parasite density is at least the minimum given.
minDensity=doubleUnits: parasites/microlitre Min: 0
The minimum density at which parasites can be detected. If 0, the test outcome is always positive.
→ scenario → diagnostics → diagnostic → stochastic
<stochastic
dens_50=double
specificity=double
/>An improved model of detection which is non-deterministic, including false positive results as well as false negatives.
The probability of a positive outcome is modelled as 1 + s×(x/(x+d) - 1) where x is the parasite density, d is the density at which the test outcome has a 50% chance of being positive, and s is the probability of a positive outcome given no parasites (the specificity).
Some parameterisations:
Microscopy sensitivity/specificity data in Africa; Source: expert opinion — Allan Schapira dens_50 = 20.0 specificity = .75
RDT sensitivity/specificity for Plasmodium falciparum in Africa Source: Murray et al (Clinical Microbiological Reviews, Jan. 2008) dens_50 = 50.0; specificity = .942;
dens_50=doubleUnits: parasites/microlitre Min: 0
The density at which the test outcome has a 50% chance of being positive.
specificity=doubleUnits: Dimensionless Min: 0 Max: 1
The probability of a positive test outcome in the absense of parasites.
<model>
IN ANY ORDER:
| <ModelOptions ... />
| <clinical ... />
| <human ... />
| [ <vivax ... /> ]
| <parameters ... />
</model>Encapsulation of all parameters which describe the model according to which fitting is done.
→ scenario → model → ModelOptions
<ModelOptions>
IN THIS ORDER:
| ( <option ... /> )*
</ModelOptions>All model options (bug fixes, choices between models, etc.).
The list of recognised options can be found in the code at:
model/util/ModelOptions.h and should also be in the wiki.
<clinical
healthSystemMemory=string
>
IN ANY ORDER:
| [ <NeonatalMortality ... /> ]
| [ <NonMalariaFevers ... /> ]
</clinical>Description of clinical parameters that are related to the health-system description, but which contain data that cannot be changed as part of an intervention and that are not restricted to treatment.
healthSystemMemory=stringUnits: User-defined (defaults to steps)
Follow-up period during which a recurrence is considered to be a treatment failure
Can be specified in steps (e.g. 6t) or days (e.g. 28d).
→ scenario → model → clinical → NeonatalMortality
<NeonatalMortality
diagnostic=string
/>diagnostic=stringThe name of a diagnostic used to parameterise the model.
Neonatal mortality is derived from malaria patency of a certain sub-population of humans. This is the diagnostic used to asses patency for this purpose.
If this is not specified, the monitoring diagnostic is used.
→ scenario → model → clinical → NonMalariaFevers
<NonMalariaFevers>
IN THIS ORDER:
| <incidence ... />
| [ <prNeedTreatmentNMF ... /> ]
| [ <prNeedTreatmentMF ... /> ]
</NonMalariaFevers>Description of the incidence of non-malaria fever. Non-malaria fevers are only modelled if the NON_MALARIA_FEVERS option is used.
→ scenario → model → clinical → NonMalariaFevers → incidence
<incidence
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</incidence>Probability that a non-malaria fever occurs given that no concurrent malaria fever occurs.
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → model → clinical → NonMalariaFevers → prNeedTreatmentNMF
<prNeedTreatmentNMF
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</prNeedTreatmentNMF>Probability that a non-malarial fever requires treatment with antibiotics (assuming fever is not induced by malaria, although concurrent parasites may be present).
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → model → clinical → NonMalariaFevers → prNeedTreatmentMF
<prNeedTreatmentMF
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</prNeedTreatmentMF>Probability that a malaria fever needs treatment with antibiotics (assuming fever is induced by malaria, although concurrent bacteria may be present).
Meaning partially overlaps with separate model for comorbidity given malaria.
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
<human>
IN THIS ORDER:
| <availabilityToMosquitoes ... />
| [ <weight ... /> ]
</human>Parameters of host models.
→ scenario → model → human → availabilityToMosquitoes
<availabilityToMosquitoes
[ interpolation=("none" or "linear") ]
>
IN THIS ORDER:
| ( <group ... /> )+
</availabilityToMosquitoes>Availability of humans to mosquitoes relative to an adult, categorized by age group
interpolation=("none" or "linear")Interpolation algorithm. Normally it is desirable for age-based values to be continuous w.r.t. age. By default linear interpolation is used.
With all algorithms except "none", the age groups are converted to a set of points centred within each age range. Extra points are added at each end (zero and infinity) to keep value constant at both ends of the function. A zero-length age group may be used as a kind of barrier to adjust the distribution; e.g. with age group boundaries at 15, 20 and 25 years, a (linear) spline would be drawn between ages 17.5 and 22.5, whereas with boundaries at 15, 20 and 20 years, a spline would be drawn between ages 17.5 and 20 years (may be desired if individuals are assumed to reach adult size at 20).
Algorithms:
- none: input values are used directly
- linear: straight lines (on an age vs. value graph) are used to interpolate data points.
→ scenario → model → human → weight
<weight
multStdDev=double
>
IN THIS ORDER:
| ( <group ... /> )+
</weight>By age group data on human weight (mass).
multStdDev=doubleUnits: None Min: 0
Each human is assigned a weight multiplier from a normal distribution with mean 1 and this standard deviation at birth. His/her weight is this multiplier times the mean from age distribution. A standard deviation of zero for no heterogeneity is valid; a rough value from Tanzanian data is 0.14.
<vivax>
IN ANY ORDER:
| <probBloodStageInfectiousToMosq ... />
| <hypnozoiteRelease ... />
| <bloodStageProtectionLatency ... />
| <bloodStageLengthDays ... />
| <clinicalEvents ... />
</vivax>- probBloodStageInfectiousToMosq
- hypnozoiteRelease
- bloodStageProtectionLatency
- bloodStageLengthDays
- clinicalEvents
→ scenario → model → vivax → probBloodStageInfectiousToMosq
<probBloodStageInfectiousToMosq
value=double
/>value=doubleA double-precision floating-point value.
→ scenario → model → vivax → hypnozoiteRelease
<hypnozoiteRelease
[ pSecondRelease=double ] DEFAULT VALUE 0
>
IN ANY ORDER:
| <numberHypnozoites ... />
| <firstRelease ... />
| [ <secondRelease ... /> ]
</hypnozoiteRelease>This element defines probabilites when and how many hypnozoites are released from the liverstage into the blood.
The gap between the start of a new brood of hypnozoites and its release are defined as follows:
latentP + latentRelapseDays + randomReleaseDelay
randomReleaseDelay is based on one or two lognormal distributions, which are defined in firstRelease and optionally secondRelease.
You can define 2 release distributions, which get added together and represent the probability of hypnozoites which get released before winter (first release) or after (second release).
You can omit the secondRelease element if no release to the blood happens after winter.
pSecondRelease=doubleDefault value: 0
Probability of a second release. If undefined it is zero.
→ scenario → model → vivax → hypnozoiteRelease → numberHypnozoites
<numberHypnozoites
max=int
base=double
/>numberHypnozoites calculates the number of hypnozoites in the liver stage based on a base which is between 0 and 1.
This number is random based on the following distribution and normalized:
max ∑ (base ^ n) n = 0
max=intbase=double→ scenario → model → vivax → hypnozoiteRelease → firstRelease
<firstRelease
latentRelapseDays=int
/>Parameters of a normal distribution.
Variates are sampled as: X ~ N( mu, sigma² ).
latentRelapseDays=intUsually 15 days or 10 days (3 or 2 5-day timesteps).
→ scenario → model → vivax → hypnozoiteRelease → secondRelease
<secondRelease
latentRelapseDays=int
/>Parameters of a normal distribution.
Variates are sampled as: X ~ N( mu, sigma² ).
latentRelapseDays=intUsually 15 days or 10 days (3 or 2 5-day timesteps).
→ scenario → model → vivax → bloodStageProtectionLatency
<bloodStageProtectionLatency
value=double
/>value=doubleA double-precision floating-point value.
→ scenario → model → vivax → bloodStageLengthDays
<bloodStageLengthDays
weibullScale=double
weibullShape=double
/>weibullScale=doubleweibullShape=double→ scenario → model → vivax → clinicalEvents
<clinicalEvents>
IN THIS ORDER:
| <pPrimaryInfection ... />
| <pRelapseOne ... />
| <pRelapseTwoPlus ... />
| <pEventIsSevere ... />
</clinicalEvents>This elements holds all information about probabilites for clinical events from infections and relapses.
→ scenario → model → vivax → clinicalEvents → pPrimaryInfection
<pPrimaryInfection
a=double
b=double
/>a=doubleb=double→ scenario → model → vivax → clinicalEvents → pRelapseOne
<pRelapseOne
a=double
b=double
/>a=doubleb=double→ scenario → model → vivax → clinicalEvents → pRelapseTwoPlus
<pRelapseTwoPlus
a=double
b=double
/>a=doubleb=double→ scenario → model → vivax → clinicalEvents → pEventIsSevere
<pEventIsSevere
value=double
/>value=doubleA double-precision floating-point value.
→ scenario → model → parameters
<parameters
interval=int
iseed=int
latentp=string
>
IN THIS ORDER:
| ( <parameter ... /> )+
</parameters>Parameters of the epidemiological model
interval=intUnits: Days
Simulation step
iseed=intUnits: Number
Seed for RNG
latentp=stringUnits: User defined (default: steps) Min: 0 Max: 20
Pre-erythrocytic latent period
Can be specified in steps (e.g. 3t) or days (e.g. 15d).
→ scenario → model → parameters → parameter
<parameter
[ name=string ]
number=int
value=double
[ include=boolean ]
/>name=stringUnits: string
Name of parameter
number=intUnits: Number Min: 1 Max: 100
Reference number of input parameter
value=doubleUnits: Number Min: 0
Parameter value
include=booleanUnits: Number Min: 0 Max: 1
True if parameter is to be sampled in optimization runs. Not used in simulator app.
| Download openmalaria | Installation instructions | XML Schema Documentation |
| XML Schema Version | Program version | master |
develop |
|---|---|---|---|
| 43 | schema-43.0 |
 |
 |