ModelTimeUpdates
- time steps are one or five days long (or both: the vector model and certain within host models use a one day time step internally even when the main simulation uses a five day step)
- a year is exactly 365 (= 5 × 73) days; leap years are not modeled
- there are two measures of time in the simulator: time since the start of the simulation (used internally but not seen in scenario XML or outputs) and time since the start of the "intervention period"
- [intervention] time 0 usually corresponds to 1st January; up to version 32 this is neither explicitly set nor required while from version 33 dates can optionally be assigned
Regarding humans:
- the maximum human age is constant, defined in the scenario XML document (
maximumAgeYrsattribute of the scenario's<demography>element) - the age at which a human is considered adult is defined as the lowest age at which human availability to mosquitoes reaches its maximum value, and extracted from the input data (see here)
Up to version 32, all durations and times are specified in relative terms, often in units of time steps. In the case of intervention deployment and survey times, the time is relative to the start of the intervention period.
From version 33, the unit of a time duration may be specified:
| 0 | zero-length duration (unit not required) |
|---|---|
| 1t | one time step (i.e. 1 or 5 days) |
| 15d | fifteen days (i.e. 3 or 15 steps) |
| 1.2y | one plus one fifth years (i.e. 1.2 × 365 days, rounded to the nearest step) |
| 2002-08-17 | 17th Aug 2002; dates are only valid if startDate is specified |
Intervention deployment and survey times may instead be specified via dates. This is done by defining the date of the start of the intervention period:
<monitoring name="..." startDate="2000-01-01">and then the deployment date (again in the format yyyy-m-d). For example:
<deploy time="2000-4-11"/>corresponds to a relative deployment time of 100 days or 20 steps (31 + 28 + 31 + 11 - 1 = 100). Note that February always has 28 days in OpenMalaria.
The following table illustrates the relationship between dates, days and timesteps.
| date | days | timestep |
|---|---|---|
| 2000-01-01 | 0 | 0 |
| 2000-01-06 | 5 | 1 |
| 2000-01-11 | 10 | 2 |
| 2000-01-16 | 15 | 3 |
| 2000-01-21 | 20 | 4 |
| 2000-01-26 | 25 | 5 |
| 2000-01-31 | 30 | 6 |
| 2000-02-05 | 35 | 7 |
| 2000-02-10 | 40 | 8 |
| 2000-02-15 | 45 | 9 |
| 2000-02-20 | 50 | 10 |
| 2000-02-25 | 55 | 11 |
| 2000-03-02 | 60 | 12 |
| 2000-03-07 | 65 | 13 |
| 2000-03-12 | 70 | 14 |
| 2000-03-17 | 75 | 15 |
| 2000-03-22 | 80 | 16 |
| 2000-03-27 | 85 | 17 |
| 2000-04-01 | 90 | 18 |
| 2000-04-06 | 95 | 19 |
| 2000-04-11 | 100 | 20 |
Also note, that for dates or days which are between timesteps OpenMalaria will round to the nearest, lower timestep. For example, the date "2000-04-10" corresponds to 99 days and will be rounded down to match timestep 19 ("2000-04-06").
The simulation proceeds roughly as follows:
- the XML document is read, model constants are set and some variables initialised
- an initial human population is created
- a warm-up period of one human life span is run
- there may be some extra simulations to adjust the mosquito population to the pre-specified Transmission situation.
- the intervention phase starts.
During these different phases the feedback from infections in humans to those in mosquitoes is handled in different ways, as explained here.
The simulation is run with enforced transmission up to time t = tWL, where tWL is at least as long as the human life span and a whole number of years.
The purpose of this period is to give all simulated humans a life-time's history of immunity. It has been speculated that this could probably be optimised away via some model for allocating initial immunity, but no work has been done to develop such a model (which must account for EIR and human heterogeneity at least, and probably several model variants and parameters).
At this point, the transmission model's initIterate() method is called. This method reports either that the transmission model is sufficiently well initialized (in which case the next phase is immediately started) or gives a length of time to continue the simulation for before this method is called again.
In the non-vector model, initIterate() prepares the model to switch to dynamic transmission mode (if enabled) and indicates the next phase should be started.
In the vector transmission model, initIterate() checks whether or not the simulated EIR could significantly better reproduce the EIR requested in the scenario file or not. If so, it makes some adjustments and indicates the simulation should continue for six years before calling initIterate() again. Once it is confirmed that the simulated EIR sufficiently approximates the requested EIR, the simulator indicates the simulation should be run for another year to let mosquito parameters stabilize before indicating that the next phase, dynamic transmission, may begin.
Especially when using the "Vector" transmission specification, users are advised to check that the transmission initialization achieves the desired periodic state at the start of the intervention period.
The initialisation algorithm was updated at v42 to reduce the frequency of this problem. This leads to differences between the initialised transmission patterns with v42 onwards, from those with earlier versions. There is no guarantee that the algorithm used for transmission initialization will converge. If a steady-state has not been achieved at the start of the intervention period, an error transmission initialisation exceeded 15 iterations will be returned. This is more likely to arise if there are many species of mosquito.
The total warm-up and initialization time could be for example 115 years. Assuming maximumAgeYrs="90" is specified in the input xml file, then the warm-up was 90 years plus 25 years for initialization.
From v44 onwards, you can observe this behavior by using the --verbose commandline option and comparing the ouput after Starting Intervention period... with your input times.
Finally, the so called "intervention period" starts: the period during which interventions may be deployed and measurements of the simulation may be taken. All times seen in the XML document and monitoring outputs are relative to the start of this period.
Only once the intervention periods starts are the constants tI₀ and tEnd known for certain. At this point the tI time measure starts being useful.
The model runs in terms of time steps: periods of fixed length over which updates happen. During a step update, the two main times of interest are the start and the end of this step. From schema version 33, these are available as sim::ts0() and sim::ts1() respectively (from model/SimTime.h); before this only the end time was directly available, as TimeStep::simulation (from include/util/TimeStep.h).
In OpenMalaria, process updates (natural inception and progression of infections, sickness events, case management and resulting outcomes, etc.) happen during a time step update. Monitoring surveys and intervention deployment, however, are modelled as happening instantaneously, between these updates (e.g. a survey at time 365 days reports on the state after the update step ending at 365 days (e.g. patency) and events happening since the previous survey or time 0 (e.g. number of deaths due to malaria)).
These times are best thought of as being midday (e.g. time 0 being noon on 1st January) and step updates as progressing from midday to midday (over one or five nights). This way monitoring, intervention deployments and on a one-day step case management all happen at midday.
Summary: at time t (sim::now() from version 33), continuous outputs and surveys due at this time are finalised, then interventions due at this time are deployed. To update from time t (sim::ts0()) to t+1 (sim::ts1()), the human population and the transmission model are updated.
This function updates humans and the transmission model:
- neonatal mortality is updated based on the previous time-step's patent hosts
- the transmission model is updated based on previous infectiousness of humans
-
Human::updateis called for each human - population age structure is maintained by out migration
- population size is maintained by adding newborns
- transmission-specific summary statistics are updated
This function updates a single human:
- number of P.f. innoculations is calculated and new infections are started
- the parasite densities are of infected humans are updated. If the 1-day time step model is used, these densities may be modified by the drugs given to the patient
- indirect deaths (neonatal and otherwise) occur
- pathogenesis state is updated based on the new parasite densities (i.e., new illnesses start)
- In the 5-day time-step model, diagnosis, medication and treatment occurs
- infant death statistics are updated
- infectiousness of human is calculated
- Humans who reach the end of the human life span (see calculation of
tWLabove) die at the end of the timestep (after continuous and discrete survey measures are taken)
Note that in five-day step models parasite density, ensuing disease, treatment seeking and most outcomes are all simulated as happening during the same step. This may hide high parasite densities from the monitoring system by treating or killing the host before monitoring happens, at the end of the step.
Used on this page:
| variable | name in code | description |
|---|---|---|
t |
TimeStep::simulation | Timestep being updated or last complete (see #Timestep_updates) |
tI |
TimeStep::interventionPeriod | Before the intervention period, tI < 0; during this period tI = t + tI₀
|
tWL |
humanWarmupLength | Length of first phase and time of its end |
tI₀ |
(none) |
t at the start of the intervention period (only known when t ≥ tI₀ ) |
tEnd |
totalSimDuration | Time at which the simulation ends (only known when t ≥ tI₀; Note, this value is determined as tI₀ + largest surveyTime element value - see description of surveyTime element) |
In the code (include/util/TimeStep.h or model/SimTime.h, depending on version):
| <= 32 | >= 33 | applicability | description |
|---|---|---|---|
| N/A | sim::ts0() |
step update | Time at the start of an update step |
TimeStep::simulation |
sim::ts1() |
step update | Time at the end of an update step |
TimeStep::simulation |
sim::now() |
monitoring/deployment | Time between updates used for monitoring and interventions |
TimeStep::interventionPeriod |
sim::intervNow() |
monitoring/deployment | Time between updates measured relative to the intervention period |
| Download openmalaria | Installation instructions | XML Schema Documentation |
| XML Schema Version | Program version | master |
develop |
|---|---|---|---|
| 43 | schema-43.0 |
 |
 |