MonitoringOptions

(Back to scenario file description.)

Monitoring options

The monitoring system is described here.

Survey measures

See here for a description of survey measures. Measures are defined in this code file: model/mon/OutputMeasures.h.

Below is a table listing the measures available for monitoring OpenMalaria simulations. The "second column" column indicates the meaning of the contents of the second column of output files and indicates whether per-chohort, per-species or per-drug outputs are enabled. The output measure is then reported separately for each age group/cohort/species/drug (if the measure is compatible and if the corresponding option is enabled, which is the default). The table below also indicates whether the measure is aggregated over the survey period (aggregated) or is the current number when the survey is taken (snapshot), as well as if the number is a real number or an integer.

| 0-29 | 30-55 | 56-64 | 65-73 | 74-78 |

Measures 0 - 29

id	measure	second column	report type	number	description
0	nHost	age group, cohort	snapshot	integer	Total number of humans. Note: when using the IPTI_SP_MODEL option, humans not at risk of a further episode due to having had a recent episode within the health-system-memory period are subtracted from this and several other outputs (only applies to the IPTI_SP_MODEL).
1	nInfect	age group, cohort	snapshot	integer	The number of human hosts with an infection (patent or not) on the reporting timestep
2	nExpectd	age group, cohort	snapshot	real	expected number of infected hosts
3	nPatent	age group, cohort	snapshot	integer	The number of human hosts whose total (blood-stage) parasite density is above the detection threshold
4	sumLogPyrogenThres	age group, cohort	snapshot	real	Sum of the log of the pyrogen threshold
5	sumlogDens	age group, cohort	snapshot	real	Sum (across hosts) of the natural logarithm of the parasite density of hosts with detectable parasite density (patent according to the monitoring diagnostic)
6	totalInfs	age group, cohort, genotype	snapshot	integer	The sum of the all infections (liver stage and blood stage, detectable or not) across all human hosts
7	nTransmit	none	snapshot	real	Infectiousness of human population to mosquitoes: sum(p(transmit_i)) across humans i, weighted by availability to mosquitoes. Single value, not per age-group.
8	totalPatentInf	age group, cohort, genotype	snapshot	integer	The sum of all detectable infections (where blood stage parasite density is above the detection limit) across all human hosts. Includes super-infections.
9					(removed)
10	sumPyrogenThresh	age group, cohort	snapshot	real	Sum of the pyrogenic threshold
11	nTreatments1	age group, cohort	aggregated	integer	number of treatments (1st line) see notes
12	nTreatments2	age group, cohort	aggregated	integer	number of treatments (2nd line) see notes
13	nTreatments3	age group, cohort	aggregated	integer	number of treatments (inpatient) see notes
14	nUncomp	age group, cohort	aggregated	integer	number of episodes (uncomplicated) An episode of uncomplicated malaria is a period during which an individual has symptoms caused by malaria parasites present at the time of illness, where the symptoms do not qualifying as severe malaria. The maximum length of the period of an episode is referred to as the health system memory and is generally set to 30 days: illness recurring within this period counts as the same episode. Illness recurring over a longer duration than this is counted as more than one episode. An illness caused by a pathogen other than malaria does not count as a malaria episode even if there is incidental parasitemia
15	nSevere	age group, cohort	aggregated	integer	number of episodes (severe) Severe malaria is a potentially life-threatening disease, diagnosable by clinical or laboratory evidence of vital organ dysfunction, requiring in-patient care. An episode of severe malaria is a period during which an individual has symptoms, qualifying as severe malaria, caused by malaria parasites present at the time of illness. As with uncomplicated malaria, the maximum duration of an episode is set to the health system memory: illness recurring over a longer duration than this is counted as more than one episode.
16	nSeq	age group, cohort	aggregated	integer	recovered cases with sequelae
17	nHospitalDeaths	age group, cohort	aggregated	integer	deaths in hospital Malaria hospitalisations in OpenMalaria are severe malaria episodes simulated as receiving in-patient care.
18	nIndDeaths	age group, cohort	aggregated	integer	number of deaths (indirect) These are deaths that occur because of malaria infection but that do not satisfy the definition of direct malaria deaths. These comprise neonatal deaths secondary to malaria in pregnancy, and deaths resulting from interactions between pathogens where malaria plays an essential role, but the terminal illness does not satisfy the definition of severe malaria.
19	nDirDeaths	age group, cohort	aggregated	integer	number of deaths (direct). This is the number of severe malaria episodes that result in death.
20	nEPIVaccinations	age group, cohort	aggregated	integer	number of EPI vaccine doses given
21	allCauseIMR	none	aggregated	integer	all cause infant mortality rate (returned as a single number over whole intervention period, instead of from a survey interval)
22	nMassVaccinations	age group, cohort	aggregated	integer	number of Mass / Campaign vaccine doses given
23	nHospitalRecovs	age group, cohort	aggregated	integer	recoveries in hospital without sequelae
24	nHospitalSeqs	age group, cohort	aggregated	integer	recoveries in hospital with sequelae
25	nIPTDoses	age group, cohort	aggregated	integer	number of IPT Doses (removed in version 32)
26	annAvgK	none	snapshot	real	Annual Average Kappa. The probability that a mosquito bite results in the mosquito becoming infected, averaged over all mosquito bites. Calculated once a year. Note: the actual calculation weights by human body size and by the input (pre-intervention) EIR to approximate the number of biting mosquitoes).
27	nNMFever	age group, cohort	aggregated	integer	Number of episodes of non-malaria fever
28					(removed)
29					(removed)

Measures 30 - 55

id	measure	second column	report type	number	description
30	innoculationsPerAgeGroup	age group, cohort, genotype	aggregated	real	The total number of inoculations per age group, summed over the reporting period. (Units are not adjusted to account for reduced child availability to mosquitoes.) Output per-cohort only from v33.
31	Vector_Nv0	vector species	snapshot	real	Number of emerging mosquitoes that survive to the first feeding search per day at this time-step (mosquito emergence rate).
32	Vector_Nv	vector species	snapshot	real	Host seeking mosquito population size at this time step.
33	Vector_Ov	vector species, genotype	snapshot	real	Number of infected host seeking mosquitoes at this time step.
34	Vector_Sv	vector species, genotype	snapshot	real	Number of infectious host seeking mosquitoes at this time step.
35	inputEIR	none	snapshot	real	(Previously Vector_EIR_Input.) Input EIR (rate entered into scenario file for vector/non-vector model). Units (schema 24 and later): total inoculations per adult over the time period since the last survey measured in infectious bites per person per time step.
36	simulatedEIR	none	snapshot	real	(Previously Vector_EIR_Simulated.) EIR generated by transmission model as measured by total inoculations received per adult since the last time step. Units as for output 35.
43	nNewInfections	age group, cohort	aggregated	integer	The number of infections introduced since the last survey, per age group. This counts super-infections without the usual limit of 21 concurrent infections, so in some ways is similar to introduction of infections in an infinite population.
52	nMDAs	age group, cohort	aggregated	integer	Number of drug doses given via mass deployment (MDA or screen&treat) (where configured as screen&treat, etc., this only reports treatments actually prescribed). As of schema 26, this output only reports anything on a 1-day time-step; in the future it will also work on a 5-day timestep.
53	nNmfDeaths	age group, cohort	aggregated	integer	Direct deaths due to non-malaria fevers
54	nAntibioticTreatments	age group, cohort	aggregated	integer	Report number of antibiotic treatments administered
55	nMassScreenings	age group, cohort	aggregated	integer	Report number of screenings used by MDA/MSAT when deployed via timed deployment

Note that the following measures are no longer available:

id	measure	second column	versions	report type	number	description
37						(removed)
38						(removed)
39	Clinical_RDTs	none	24-31	aggregated	integer	Number of Rapid Diagnostic Tests used
40	Clinical_DrugUsage	drug ID	24-31	aggregated	integer	Quantities of oral drugs used, per active ingredient abbreviation (mg)
41	Clinical_FirstDayDeaths	age group	24-	aggregated	integer	Direct death before treatment takes effect
42	Clinical_HospitalFirstDayDeaths	age group	24-	aggregated	integer	Direct death before treatment takes effect; hospital only
44	nMassITNs	age group	24-	aggregated	integer	The number of ITNs delivered by mass distribution since last survey.
45	nEPI_ITNs	age group	24-	aggregated	integer	The number of ITNs delivered through EPI since last survey.
46	nMassIRS	age group	24-	aggregated	integer	The number of people newly protected by IRS since last survey.
47	nMassVA	age group	24-31	aggregated	integer	The number of people newly protected by a vector-availability intervention since the last survey. (removed in version 32)
48	Clinical_Microscopy	none	24-31	aggregated	integer	Number of microscopy tests used
49	Clinical_DrugUsageIV	drug ID	24-31	aggregated	integer	Quantities of intravenous drugs used, per active ingredient abbreviation (mg)
50	nAddedToCohort	age group	32-	aggregated	integer	Number of individuals added to any cohort. Note that the reporting happens after updating membership details (Removed in version 32).
51	nRemovedFromCohort	age group	32-	aggregated	integer	Number of individuals removed from any cohort. Note that the reporting happens before updating membership details (Removed in version 32).

Measures 56 - 64 (added in schema 32)

id	measure	second column	report type	number	description
56	nMassGVI	age group, cohort	aggregated	integer	Report the number of mass deployments of generic vector interventions
57	nCtsIRS	age group, cohort	aggregated	integer	Report the number of IRS deployments via age-based deployment
58	nCtsGVI	age group, cohort	aggregated	integer	Report the number of GVI deployments via age-based deployment
59	nCtsMDA	age group, cohort	aggregated	integer	Report the number of MDA deployments via age-based deployment
60	nCtsScreenings	age group, cohort	aggregated	integer	Report the number of screenings used by MDA/MSAT when deployed via age-based deployment
61	nSubPopRemovalTooOld	age group, cohort	aggregated	integer	Number of removals from a sub-population due to expiry of duration of membership (e.g. intervention too old).
62	nSubPopRemovalFirstEvent	age group, cohort	aggregated	integer	Number of removals from a sub-population due to first infection/bout/treatment (see onFirstBout & co).
63	nLiverStageTreatments	age group, cohort	aggregated	integer	Number of liver-stage treatments administered see notes
64	nTreatDiagnostics	age group, cohort	aggregated	integer	Number of diagnostic tests performed (if in the health system description, useDiagnosticUC="true").

Measures 65 - 73 (added in schema 33)

id	measure	second column	report type	number	description
65	nMassRecruitOnly	age group, cohort	aggregated	integer	Number of "recruitment only" recruitments via timed deployment.
66	nCtsRecruitOnly	age group, cohort	aggregated	integer	Number of "recruitment only" recruitments via age-based deployment.
67	nTreatDeployments	age group, cohort	aggregated	integer	Number of deployments (of all intervention components) triggered by treatment (case management).
68	sumAge	age group, cohort	snapshot	real	Report the total age of all humans in this a group (sum across humans,in years). Divide by nHost to get the average age.
69	nInfectByGenotype	age group, cohort	snapshot	integer	The number of human hosts with an infection (patent or not), for each genotype, at the time the survey is taken.
70	nPatentByGenotype	age group, cohort	snapshot	integer	The number of human hosts whose total (blood-stage) parasite density, for each genotype, is above the detection threshold
71	logDensByGenotype	age group, cohort	snapshot	real	For each infection genotype, sum across humans the natural log of parasite density (like sumlogDens but per genotype).
72	nHostDrugConcNonZero	age group, cohort	snapshot	integer	For each drug type in the pharmacology section of the XML, report the number of humans with non-zero concentration of this drug in their blood.
73	sumLogDrugConcNonZero	age group, cohort	snapshot	real	For each drug type in the pharmacology section of the XML, report the sum of the natural logarithm of the drug concentration in hosts with non-zero concentration.

Measures 74 - 78 (added in schema 35)

These add expected counts of deaths and cases of severe disease, calculated by adding up the probabilities of events occurring across all relevant humans. These measures are included in order to enable prediction of relatively rare events in small simulations, and are an alternative to measure 16-19 which output counts of discrete events.

Expected direct deaths (74, 75) and sequelae (77) are calculated from the sum over all steps in the reporting period of the sum over humans with severe malaria of the probability of direct death/sequelae, where 75 is the sub-set who are also in hospital. There may be a selection bias in the expected number of deaths computed in this way because unlike deaths counted by measures 17 and 19, the computation of expected deaths does not result in selective removal of susceptible individuals from the population.

Expected number of indirect deaths

This is calculated as the sum over all steps in the reporting period of the sum over humans with a malaria bout (severe or not) of the probability of indirect death due to malaria, assuming that they do not die of another cause in the mean-time.

Indirect death is only possible in the simulation when the individual is sick, so the expected number of such events can be used to estimate the case fatality rate (using sick humans as the denominator), or the mortality rate (using all humans as the denominator). There is a small bias in the expected number of indirect deaths computed this way, because the probability of indirect death is calculated ahead of the actual death and individuals may be removed from the population at risk earlier than the specified date of death (e.g. owing to direct deaths, or outmigration). Humans already 'doomed' to die as an 'indirect mortality' are excluded from the computation of expected rates of indirect mortality. There may also be a selection bias in the expected number of indirect deaths computed in this way because unlike indirect deaths counted by measure 18, the computation of expected deaths does not result in selective removal of susceptible individuals from the population.

Expected number of bouts of severe malaria.

This is calculated as the sum over all steps in the reporting period and over all malaria bouts (severe or not) of the bout becoming severe. For 5-day time-steps this is calculated once per bout (which lasts one time-step). For other time-steps exact behaviour is not yet defined. This includes both severe malaria resulting from hyperparasitaemia or from complications due to coinfection (as with the nSevere output). There may also be a selection bias in the expected number of bouts of severe malaria computed in this way because unlike severe episodes counted by measure 15, the computation of expected bouts does not result in selective treatment of susceptible individuals.

id	measure	second column	report type	number	description
74	expectedDirectDeaths	age group, cohort	snapshot	real	Expected number of direct malaria deaths, from those with severe disease.
75	expectedHospitalDeaths	age group, cohort	snapshot	real	Subset of measure 74 which occur in hospital.
76	expectedIndirectDeaths	age group, cohort	snapshot	real	Expected number of indirect malaria deaths (see notes above).
77	expectedSequelae	age group, cohort	snapshot	real	Expected number of sequelae, from those with severe disease.
78	expectedSevere	age group, cohort	snapshot	real	Expected number of severe bouts of malaria (see notes above).

EIR per species

Added in schema-40.3:

id	measure	second column	report type	number	description
79	innoculationsPerVector	vector species	snapshot	real	Inoculations per vector (same as output 30 but by species).

Continuous measures

Continuous measures are output for regular time periods in the simulation. This output format was introduced in schema version 19; some outputs were added later. To enable continuous outputs a 'continuous' element must precede the 'SurveyOptions' element within the monitoring section of the XML. Each different continous output is enabled by adding a sub-element to continuous.

For example:

<continuous period="1">
  <option name="input EIR" value="true"/>
</continuous>

The continuous output appears in the text file 'ctsout.txt' (see also the description of outputs).

The following table lists the measures that can be monitored in this way. The 'versions' column lists the OpenMalaria versions for which this output is available, going back as far as version 30 (previous history was not checked).

output	versions	description
N_v0	from 30	The number of mosquitoes that emerge and survive to first host seeking, per day (mosquito emergence rate)
N_v	from 30	The total number of host seeking mosquitoes
O_v	from 30	The number of infected host seeking mosquitoes
S_v	from 30	The number of infectious host seeking mosquitoes
P_A	from 30	The probability that a mosquito doesn't find a host and doesn't die on given night
P_df	from 30	The probability that a mosquito finds a host on a given night, feeds and survives to return to the host-seeking population
P_dif	from 30	The probability that a mosquito finds a host on a given night, feeds, gets infected with P. falciparum and survives to return to the host-seeking population
alpha	from 30.1	The availability rate of humans to mosquitoes (averaged across human population); units: humans/day (I think)
P_B	from 30.1	The probability of a mosquito successfully biting a human after choosing, averaged across humans
P_C*P_D	from 30.1	The probability of a mosquito successfully escaping a human and resting after biting, averaged across humans
P_Amu	from 43.0	The probability that a mosquito dies on a given night
P_A1	from 43.0	The probability that a mosquito finds a human host on a given night
P_Ah	from 43.0	The probability that a mosquito finds a non-human host on a given night
input EIR	from 30	Requested entomological infection rate. This is a fixed periodic value, for comparison with simulated EIR. Units (from schema version 24): inoculations per adult per timestep.
simulated EIR	from 30	EIR acting on simulated humans. Units: from schema version 26, inoculations per adult per timestep, previously inoculations per person per timestep.
hosts	from 30	Total number of human hosts (fixed)
host demography	from 30	Number of humans less than 1, 5, 10, 15, and 25 years of age respectively
recent births	from 30	Number of new humans since last report
patent hosts	from 30	Number of humans with detectible parasite density
human infectiousness	from 30	Infectiousness of humans to mosquitoes, also known as kappa. This is the probability that a mosquito becomes infected at any single feed on a human.
human age availability	from 30	Mean age-based availability of humans to mosquitoes relative to a human adult (doesn't include any other availability factors, such as vector-model rate or intervention protections).
immunity h	from 30	Average of _cumulativeh parameter across humans, which is the cumulative number of infections received since birth
immunity Y	from 30	Average (mean) of _cumulativeY parameter across humans, which is the cumulative parasite density since birth
median immunity Y	from 30	Average (median) of _cumulativeY parameter across humans, which is the cumulative parasite density since birth
new infections	from 30	Number of new infections since last report, including super infections as with survey measure 43.
num transmitting humans	from 30	Number of humans who are infectious to mosquitoes
nets owned	30 - 31	Number of people owning a bed net. Note that people cannot own more than one of a single type of net, so this is usually also the number of nets owned. For version 32, use ITN coverage instead.
ITN coverage	from 32	The number of people owning any type of net divided by the population size. This does not count nets parameterised with the "GVI" model, only those using the "ITN" model.
IRS coverage	from 32	The number of people currently protected by any type of IRS divided by the population size. It does not count IRS configured with the "GVI" model.
GVI coverage	from 32	The number of people currently protected by any GVI (generic vector intervention) divided by the population size. Note that even if "GVI" is used to model two very different interventions (e.g. deterrents and nets), this is the coverage by "at least one of" these interventions, not separate coverage levels. This includes nets, IRS and other interventions modelled using the "GVI" intervention model but not those using the separate "ITN" or "IRS" models.
mean hole index	30 - 31	Average hole-index of all nets (will be not-a-number when no nets are owned)
mean insecticide content	30 - 31	Average insecticide content of all nets in mg/m² (will be not-a-number when no nets are owned)
IRS insecticide content	30.1 - 31	Average insecticide content of hut walls over all houses (new IRS model version 2 only); added in schema 30
IRS effects	30.1 - 31	Average effect of IRS on the following three factors: availablity to mosquitoes, preprandial killing, postprandial killing; mean across all humans; both IRS models version 1 and 2; added in schema 30
resource availability	from 30.3	Mean larval resources over a time-step (1/γ for these models)
requirements availability	from 30.3	Only for an as-yet unavailable mosquito population dynamics model

There is no central list of these outputs in the code; instead search for calls to Continuous::registerCallback -- with an initial argument corresponding to the output identifier in the table above.

Notes

Treatments

Reporting of treatments was added to the 1-day models in version 24.1.

As of OpenMalaria version 34, nTreatments1/2/3 are used to count the number of blood-stage treatments used and do not count liver-stage treatments, with the following exceptions: (1) the ImmediateOutcomes model reports a treatment whenever cure rate and compliance probabilities indicate that one should be given; however it is possible that the health-system could have treatment actions configured to do nothing or administer liver-stage treatments only, (2) any PK/PD model treatments given are counted even if no blood-stage drugs are used, (3) if a decision tree deploys an intervention this is counted as a treatment, (4) the decision tree node "treatment failure" is counted.

nLiverStageTreatments reports usage of any liver-stage treatments (from version 34.x as above) and thus is not Primaquine-specific (renamed from nPQTreatments).

Missing values

Some outputs are the result of averaging a measure over the number of simulated individuals for a specified duration. If the denominator number of individuals in this average is zero, the resulting value isn't valid, so an output value of nan (or "-nan" - short for Not A Number) is reported. To make detection of computation errors easier, we try to avoid outputting nan values in discrete survey outputs. The same is not true for continuous outputs: several of these may output nan values at the beginning of the simulation or other times.

For the drug costing measures no value is listed at all for drugs never prescribed since the last survey.

EIR Units

The units we generally use for EIR are entomological inoculations per time period as measured in adults where the time period may be days, years, or the model's time step (currently 1 or 5 days).

Since children are smaller than adults our model assumes they are less likely to be bitten by mosquitoes. However, most information we have on EIR tends to be measured in adults. We try to make our units equivalent, either by only considering bites in adults or by scaling the mean availability of all people in the population (children and adults) compared to a population composed only of adults (this mean relative availability is the "human availability" output available in continuous-reporting mode).