Welcome to EMOD HIV modeling

The Institute for Disease Modeling (IDM) develops disease modeling software that is thoroughly tested and shared with the research community to advance the understanding of disease dynamics. This software helps determine the combination of health policies and intervention strategies that can lead to disease eradication. If you encounter any issues while using the software, please contact support@idmod.org.

Epidemiological MODeling software (EMOD), is an agent-based model (ABM) that simulates the simultaneous interactions of agents in an effort to recreate complex phenomena. Each agent (such as a human or vector) can be assigned a variety of “properties” (for example, age, gender, etc.), and their behavior and interactions with one another are determined by using decision rules. These models have strong predictive power and are able to leverage spatial and temporal dynamics.

EMOD is also stochastic, meaning that there is randomness built into the model. Infection and recovery processes are represented as probabilistic Bernoulli random draws. In other words, when a susceptible person comes into contact with a pathogen, they are not guaranteed to become infected. Instead, you can imagine flipping a coin that has a λ chance of coming up tails S(t) times, and for every person who gets a “head” you say they are infected. This randomness better approximates what happens in reality. It also means that you must run many simulations to determine the probability of particular outcomes.

Documentation structure

Using the model contains information that will help you get started with EMOD, including installation instructions, a basic overview of the software, and some example simulations you can run on your computer.

Understanding the model contains more detailed information about the disease biology, workings of the EMOD model, complete parameter reference, and a glossary.

Advancing the model contains information for researchers and developers who want to modify the EMOD source code to add more functionality to the model.

The EMOD documentation is broken up into disease-specific sets that provide guidance for researchers modeling particular diseases. The documentation contains only the parameters, output reports, and other components of the model that are available to use with this disease model.

For example, this documentation set includes general installation and usage instructions that are common in all simulation types in addition to content specific to modeling HIV and other sexually transmitted infections.

What’s new

This topic describes new functionality and breaking changes for recently released versions of Epidemiological MODeling software (EMOD).

EMOD v2.20

The EMOD v2.20 release includes support for typhoid disease modeling, including new campaign classes: EnvironmentalDiagnostic, TyphoidCarrierDiagnostic, TyphoidVaccine, and TyphoidWASH.

ImmunityBloodTest was added for identifying whether an individual’s immunity meets a specified threshold and then broadcasts an event based on the results. This new campaign class can be used with all supported disease modeling sim types.

InterventionForCurrentPartners can be used with STI and HIV sim types and provides a mechanism for the partners of individuals in the care system to also seek care.

OutbreakIndividualTBorHIV extends OutbreakIndividual and allows for specifying HIV or a specific strain of infection for TB.

In addition, configuration and campaign parameters that set the type of distribution (uniform, Gaussian, etc.) of infectiousness, incubation period, and delivery of interventions have been refactored. The number of distributions available and naming conventions used are now consistent across the configuration and campaign files. This change does not affect the distributions used in the demographics files.

A beta release of new campaign classes (not yet fully tested) are included to support surveillance of events, where events are listened to, detected, and broadcast when a threshold has been met. These classes include: BroadcastCoordinatorEvent, BroadcastNodeEvent, DelayEventCoordinator, SurveillanceEventCoordinator, and TriggeredEventCoordinator.

New configuration parameters

For the generic simulation type, the following new configuration parameters are available:

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Enable_Infectivity_Reservoir

boolean

0

1

0

Controls whether or not an exogeneous reservoir of infectivity will be included in the simulation and allows for the infectivity in a node to be increased additively. When set to 1 (true), the demographics parameter InfectivityReservoirSize is expected in NodeAtttributes for each node.

 
{
    "Enable_Infectivity_Reservoir": 1
}

Enable_Abort_Zero_Infectivity

boolean

0

Controls whether or not the simulation should be ended when total infectivity falls to zero. Supported only in single-node simulations.

 
{
    "Enable_Abort_Zero_Infectivity": 1,
    "Minimum_End_Time": 3650
}

Enable_Random_Generator_From_Serialized_Population

boolean

0

Determines if the random number generator(s) should be extracted from a serialized population file. Enabling this will start a simulation from this file with the exact same random number stream and location in that stream as when the file was serialized.

 
{
    "Run_Number": 12,
    "Random_Number_Generator_Type": "USE_AES_COUNTER",
    "Random_Number_Generator_Policy": "ONE_PER_NODE",
    "Enable_Random_Generator_From_Serialized_Population": 1
}

Minimum_End_Time

float

0

1000000

0

The minimum time step the simulation must reach before checking for early termination conditions. Enable_Abort_Zero_Infectivity must be set to 1 (true).

 
{
    "Enable_Abort_Zero_Infectivity": 1,
    "Minimum_End_Time": 3650
}

Random_Number_Generator_Policy

enum

ONE_PER_CORE

The policy that determines if random numbers are generated for objects in a simulation on a per-core or per-node basis. The following values are available:

ONE_PER_CORE

A random number generator (RNG) is created for each computing core running a simulation. When running a simulation on a single core, there will be only one RNG. If running the single simulation on multiple cores, each core will have its own RNG. The RNGs on the different cores start out such that they will not generate the same stream of random numbers. Prior to EMOD 2.19, all simulations used this policy.

ONE_PER_NODE

An RNG is created for each geographic node in the simulation. The advantages of this policy are that 1) an event that causes a random number to be drawn in one node does not cause things to change in another node and 2) changing a simulation from single core to multi-core will not change the results. The RNGs on the different nodesstart out such that they will not generate the same stream of random numbers.

 
{
    "Run_Number": 15,
    "Random_Number_Generator_Type": "USE_AES_COUNTER",
    "Random_Number_Generator_Policy": "ONE_PER_NODE"
}

Random_Number_Generator_Type

enum

USE_PSEUDO_DES

The type of random number generator to use for objects in a simulation. Must set the RNG seed in Run_Number. The following values are available:

USE_PSEUDO_DES

Based on Numerical Recipes in C. The Art of Scientific Computing, 2nd ed. Press, William H. et. al, 1992. Prior to EMOD 2.19, this was the only generator available.

USE_LINEAR_CONGRUENTIAL

Based on The Structure of Linear Congruential Sequences, Marsaglia, George, 1972.

USE_AES_COUNTER

Based on AES in CTR Mode encryption as implemented in Intel (R) Advanced Encryption Standard (AES) New Instruction Set.

 
{
    "Run_Number": 15,
    "Random_Number_Generator_Type": "USE_LINEAR_CONGRUENTIAL",
    "Random_Number_Generator_Policy": "ONE_PER_NODE",
    "Enable_Random_Generator_From_Serialized_Population": 1
}
New configuration parameters (Distribution)

Note: These configuration parameters are part of the refactoring of distribution parameters.

For the generic simulation type, the following new configuration parameters are available:

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Incubation_Period_Constant

float

0

3.40E+38

6

The incubation period to use for all individuals.

 
{
    "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Incubation_Period_Constant": 8
}

Incubation_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the incubation period to each individual in the population. Each individual’s value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Incubation_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Incubation_Period_Max and Incubation_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Set Incubation_Period_Gaussian_Mean and Incubation_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Incubation_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Incubation_Period_Kappa and Incubation_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Incubation_Period_Log_Normal_Mu and Incubation_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Incubation_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Incubation_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Incubation_Period_Mean_1, Incubation_Period_Mean_2, and Incubation_Period_Proportion_1. This distribution does not use the parameters set for DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Exponential

float

0

3.40E+38

6

The mean incubation period when Incubation_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Exponential": 4.25
}

Incubation_Period_Gaussian_Mean

float

0

3.40E+38

6

The mean of the incubation period when Incubation_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Gaussian_Std_Dev

float

1.18E-38

3.40E+38

1

The standard deviation of the incubation period when Incubation_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Kappa

float

1.18E-38

3.40E+38

1

The shape value for the incubation period when Incubation_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Incubation_Period_Kappa": 0.9,
    "Incubation_Period_Lambda": 1.5
}

Incubation_Period_Lambda

float

1.18E-38

3.40E+38

1

The scale value for the incubation period when Incubation_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Incubation_Period_Kappa": 0.9,
    "Incubation_Period_Lambda": 1.5
}

Incubation_Period_Log_Normal_Mu

float

1.18E-38

3.40E+38

6

The mean of the natural log of the incubation period when Incubation_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Incubation_Period_Log_Normal_Mu": 4,
    "Incubation_Period_Log_Normal_Sigma": 1
}

Incubation_Period_Log_Normal_Sigma

float

1.18E-38

3.40E+38

1

The standard deviation of the natural log of the incubation period when Incubation_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Incubation_Period_Log_Normal_Mu": 4,
    "Incubation_Period_Log_Normal_Sigma": 1
}

Incubation_Period_Max

float

0

3.40E+38

1

The maximum incubation period when Incubation_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Incubation_Period_Min": 2,
    "Incubation_Period_Max": 7
}

Incubation_Period_Mean_1

float

1.18E-38

3.40E+38

1

The mean of the first exponential distribution when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Incubation_Period_Mean_2

float

1.18E-38

3.40E+38

1

The mean of the second exponential distribution when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Incubation_Period_Min

float

0

3.40E+38

0

The minimum incubation period when Incubation_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Incubation_Period_Min": 2,
    "Incubation_Period_Max": 7
}

Incubation_Period_Peak_2_Value

float

0

3.40E+38

1

The incubation period value to assign to the remaining individuals when Incubation_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Incubation_Period_Proportion_0": 0.25,
    "Incubation_Period_Peak_2_Value": 5
}

Incubation_Period_Poisson_Mean

float

0

3.40E+38

6

The mean of the incubation period when Incubation_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "POISSON_DISTRIBUTION",
    "Incubation_Period_Poisson_Mean": 5
}

Incubation_Period_Proportion_0

float

0

1

1

The proportion of individuals to assign a value of zero days incubation when Incubation_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Incubation_Period_Proportion_0": 0.25,
    "Incubation_Period_Peak_2_Value": 5
}

Incubation_Period_Proportion_1

float

0

1

1

The proportion of individuals in the first exponential distribution when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Infectious_Period_Constant

float

0

3.40E+38

6

The infectious period to use for all individuals.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Infectious_Period_Constant": 8
}

Infectious_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the infectious period to each individual in the population. Each individual’s value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Infectious_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Infectious_Period_Max and Infectious_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Set Infectious_Period_Gaussian_Mean and Infectious_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Infectious_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Infectious_Period_Kappa and Infectious_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Infectious_Period_Log_Normal_Mu and Infectious_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Infectious_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Infectious_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Infectious_Period_Mean_1, Infectious_Period_Mean_2, and Infectious_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Exponential

float

0

3.40E+38

6

The mean infectious period when Infectious_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Exponential": 4.25
}

Infectious_Period_Gaussian_Mean

float

0

3.40E+38

6

The mean of the infectious period when Infectious_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Gaussian_Std_Dev

float

1.18E-38

3.40E+38

1

The standard deviation of the infectious period when Infectious_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Kappa

float

1.18E-38

3.40E+38

1

The shape value for the infectious period when Infectious_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Infectious_Period_Kappa": 0.9,
    "Infectious_Period_Lambda": 1.5
}

Infectious_Period_Lambda

float

1.18E-38

3.40E+38

1

The scale value for the infectious period when Infectious_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Infectious_Period_Kappa": 0.9,
    "Infectious_Period_Lambda": 1.5
}

Infectious_Period_Log_Normal_Mu

float

1.18E-38

3.40E+38

6

The mean of the natural log of the infectious period when Infectious_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Infectious_Period_Log_Normal_Mu": 9,
    "Infectious_Period_Log_Normal_Sigma": 2
}

Infectious_Period_Log_Normal_Sigma

float

1.18E-38

3.40E+38

1

The standard deviation of the natural log of the infectious period when Infectious_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Infectious_Period_Log_Normal_Mu": 9,
    "Infectious_Period_Log_Normal_Sigma": 2
}

Infectious_Period_Max

float

0

3.40E+38

1

The maximum infectious period when Infectious_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Infectious_Period_Min": 2,
    "Infectious_Period_Max": 7
}

Infectious_Period_Mean_1

float

1.18E-38

3.40E+38

1

The mean of the first exponential distribution when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Infectious_Period_Mean_2

float

1.18E-38

3.40E+38

1

The mean of the second exponential distribution when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Infectious_Period_Min

float

0

3.40E+38

0

The minimum infectious period when Infectious_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Infectious_Period_Min": 2,
    "Infectious_Period_Max": 7
}

Infectious_Period_Peak_2_Value

float

0

3.40E+38

1

The infectious period value to assign to the remaining individuals when Infectious_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Infectious_Period_Proportion_0": 0.25,
    "Infectious_Period_Peak_2_Value": 5
}

Infectious_Period_Poisson_Mean

float

0

3.40E+38

6

The mean of the infectious period with Infectious_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "POISSON_DISTRIBUTION",
    "Infectious_Period_Poisson_Mean": 5
}

Infectious_Period_Proportion_0

float

0

1

1

The proportion of individuals to assign a value of zero days infectiousness when Infectious_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Infectious_Period_Proportion_0": 0.25,
    "Infectious_Period_Peak_2_Value": 5
}

Infectious_Period_Proportion_1

float

0

1

1

The proportion of individuals in the first exponential distribution when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Symptomatic_Infectious_Offset

float

-3.40E+38

3.40E+38

3.40E+38

Amount of time, in days, after the infectious period starts that symptoms appear. Negative values imply an individual is symptomatic before infectious. If this offset is greater than the infectious duration, the infection will not be symptomatic. For example, if Incubation_Period_Constant is set to 10 and Symptomatic_Infectious_Offset is set to 4, then an infected person would become symptomatic 14 days after transmission.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Symptomatic_Infectious_Offset": 4,
    "Incubation_Period_Constant": 10
}

Symptomatic_Infectious_Offset

float

-3.40E+38

3.40E+38

3.40E+38

Amount of time, in days, after the infectious period starts that symptoms appear. Negative values imply an individual is symptomatic before infectious. If this offset is greater than the infectious duration, the infection will not be symptomatic. For example, if Incubation_Period_Constant is set to 10 and Symptomatic_Infectious_Offset is set to 4, then an infected person would become symptomatic 14 days after transmission.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Symptomatic_Infectious_Offset": 4,
    "Incubation_Period_Constant": 10
}
New configuration parameters (Beta)

Note: These configuration parameters are currently in beta release and have not yet been fully tested.

For the generic simulation type, the following new configuration parameters are available:

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Report_Coordinator_Event_Recorder

boolean

0

Enables or disables the ReportCoordinatorEventRecorder.csv output report for coordinator events. When enabled (set to 1) reports will be generated for the broadcasted valid coordinator events, as specified in Report_Coordinator_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Report_Coordinator_Event_Recorder_Events

array of strings

NA

The list of events to include or exclude in the ReportCoordinatorEventRecorder.csv output report, based on how Report_Coordinator_Event_Recorder_Ignore_Events_In_List is set. This list must not be empty and is dependent upon Report_Coordinator_Event_Recorder being enabled. In addition, the events must be defined in Customer_Coordinator_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Report_Coordinator_Event_Recorder_Ignore_Events_In_List

boolean

0

If set to false (0), only the events listed in the Report_Coordinator_Event_Recorder_Events array will be included in the ReportCoordinatorEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Node_Event_Recorder

boolean

0

Enables or disables the ReportNodeEventRecorder.csv output report. When enabled (set to 1) reports will be generated for the broadcasted valid node events, as specified in Report_Node_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ]
}

Report_Node_Event_Recorder_Events

array of strings

NA

The list of node events to include or exclude in the ReportNodeEventRecorder.csv output report, based on how Report_Node_Event_Recorder_Ignore_Events_In_List is set.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Node_Event_Recorder_Ignore_Events_In_List

boolean

0

If set to false (0), only the node events listed in the Report_Node_Event_Recorder_Events array will be included in the ReportNodeEventRecorder.csv output report. If set to true (1), only the node events listed in the array will be excluded, and all other node events will be included. If you want to return all node events from the simulation, leave the node events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

Value

Events array

Output file

0

No events

No events

0

One or more events

Only the listed events.

1

No events

All events occurring in the simulation.

1

One or more events

All simulation events occurring in the simulation, except for those listed.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Node_Event_Recorder_Node_Properties

array of strings

[]

Specifies an array of (optional) node property keys, as defined in NodeProperties in the demographics file, to be added as additional columns to the ReportNodeEventRecorder.csv output report.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0,
    "Report_Node_Event_Recorder_Node_Properties": [
        "Geographic"
    ]
}

Report_Node_Event_Recorder_Stats_By_IPs

array of strings

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the ReportNodeEventRecorder.csv output report. For each key:value pair there will be two additional columns (Key:Value:NumIndividuals, Key:Value:NumInfected) added to the report. For example, with a Risk property key assigned the values of LOW and HIGH there would then be four additional columns (Risk:LOW:NumIndividuals, Risk:LOW:NumInfected, Risk:HIGH:NumIndividuals, Risk:HIGH:NumInfected). An empty array equals no additional columns added.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0,
    "Report_Node_Event_Recorder_Node_Properties": [
        "Geographic"
    ],
    "Report_Node_Event_Recorder_Stats_By_IPs": [
        "Risk"
    ]
}

Report_Surveillance_Event_Recorder

boolean

0

Enables or disables the ReportSurveillanceEventRecorder.csv output report. When enabled (set to 1) reports will be generated for the broadcasted valid coordinator events, as specified in Report_Surveillance_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ]
}

Report_Surveillance_Event_Recorder_Events

array of strings

NA

The list of events to include or exclude in the ReportSurveillanceEventRecorder.csv output report, based on how Report_Surveillance_Event_Recorder_Ignore_Events_In_List is set. This list must not be empty and is dependent upon Report_Surveillance_Event_Recorder being enabled.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ]
}

Report_Surveillance_Event_Recorder_Ignore_Events_In_List

boolean

0

If set to false (0), only the events listed in the Report_Surveillance_Event_Recorder_Events array will be included in the ReportSurveillanceEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

Value

Events array

Output file

0

No events

No events

0

One or more events

Only the listed events.

1

No events

All events occurring in the simulation.

1

One or more events

All simulation events occurring in the simulation, except for those listed.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Surveillance_Event_Recorder_Stats_By_IPs

array of strings

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the ReportSurveillanceEventRecorder.csv output report. For each key:value pair there will be two additional columns (Key:Value:NumIndividuals, Key:Value:NumInfected) added to the report. For example, with a Risk property key assigned the values of LOW and HIGH there would then be four additional columns (Risk:LOW:NumIndividuals, Risk:LOW:NumInfected, Risk:HIGH:NumIndividuals, Risk:HIGH:NumInfected). An empty array equals no additional columns added.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder_Stats_By_IPs": []
}
New demographics parameters

In all simulation types, you can now specify the quantity-per-timestep added to the total infectivity present in a node; it is equivalent to the expected number of additional infections in a node, per timestep. For example, if timestep is equal to a day, then setting InfectivityReservoirSize to a value of 0.1 would introduce an infection every 10 days from the exogenous reservoir.

For more information, see the table below.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

InfectivityReservoirEndTime

float

InfectivityReservoirStartTime

3.40E+38

3.40E+38

The ending of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}

InfectivityReservoirSize

float

0

3.40E+38

0

The quantity-per-timestep added to the total infectivity present in a node; it is equivalent to the expected number of additional infections in a node, per timestep. For example, if timestep is equal to a day, then setting InfectivityReservoirSize to a value of 0.1 would introduce an infection every 10 days from the exogenous reservoir. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}

InfectivityReservoirStartTime

float

0

3.40E+38

0

The beginning of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}
New campaign parameters

The following campaign classes are new and can be used in the (specified) models:

ImmunityBloodTest (generic)

The ImmunityBloodTest intervention class identifies whether an individual’s immunity meets a specified threshold (as set with the Positive_Threshold_AcquisitionImmunity campaign parameter) and then broadcasts an event based on the results; positive has immunity while negative does not.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Treatment_Fraction": 1,
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "class": "ImmunityBloodTest"
        }
    }
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until diagnosis.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Disqualifying_Properties": [
                "InterventionStatus:LostForever"
            ],
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Dont_Allow_Duplicates": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Enable_IsSymptomatic

boolean

NA

NA

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Intervention_Name

string

NA

NA

ImmunityBloodTest

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Intervention_Name": "Immunity Blood Test - Series 1",
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative (does not have immunity), then an individual type event is broadcast; custom individual events can be defined in the config parameter Custom_Individual_Events. This may trigger another intervention when the event occurs.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive (has immunity), then an individual type event is broadcast; custom individual events can be defined in the config parameter Custom_Individual_Events. This may trigger another intervention when the event occurs.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Positive_Threshold_AcquisitionImmunity

float

0

1

1

Specifies the threshold for acquired immunity, where 1 equals 100% immunity and 0 equals 100% susceptible.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}
InterventionForCurrentPartners (HIV, STI)

The InterventionForCurrentPartners intervention class provides a mechanism for the partners of individuals in the care system to also seek care. Partners do not need to seek testing at the same time; a delay may occur between the initial test and the partner’s test. If a relationship has been paused, such as when a partner migrates to a different node, the partner will not be contacted.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The event that is immediately broadcast to the partner. Required if Event_or_Config is set to Event. See Event list for possible built-in values, or create custom values using Custom_Individual_Events.

 
{
    "Broadcast_Event": "HIVNewlyDiagnosed"
}

Disqualifying_Properties

array of strings

NA

NA

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Event"
}

Intervention_Config

JSON object

The intervention definition that is immediately distributed to the partner. Required if Event_Or_Config is set to Config.

 
{
    "class": "StandardInterventionDistributionEventCoordinator",
    "Intervention_Config": {
        "class": "NodeLevelHealthTriggeredIV",
        "Trigger_Condition_List": [
            "Some_Other_Event"
        ],
        "Actual_IndividualIntervention_Config": {
            "class": "InterventionForCurrentPartners",
            "Disqualifying_Properties": [],
            "New_Property_Value": "CascadeState:TestingCurrentPartner",
            "Relationship_Types": [
                "MARITAL",
                "INFORMAL",
                "TRANSITORY",
                "COMMERCIAL"
            ],
            "Minimum_Duration_Years": 0.5,
            "Prioritize_Partners_By": "LONGER_TIME_IN_RELATIONSHIP",
            "Maximum_Partners": 2,
            "Event_Or_Config": "Event",
            "Broadcast_Event": "HIVNewlyDiagnosed"
        }
    }
}

Intervention_Name

string

NA

NA

InterventionForCurrentPartners

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "Intervention_Name": "Intervention_For_Spouse",
        "class": "InterventionForCurrentPartnersr"
    }
}

Maximum_Partners

integer

0

1000

100

The maximum number of partners that will receive the intervention. Required when Prioritize_Partners_By is not set to NO_PRIORITIZATION.

 
{
    "Prioritize_Partners_By": "NO_PRIORITIZATION",
    "Maximum_Partners": 2
}

Minimum_Duration_Years

float

0

200

0

The minimum amount of time, in years, between relationship formation and the current time for the partner to qualify for the intervention.

 
{
    "Minimum_Duration_Years": 0.5
}

New_Property_Value

string

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prioritize_Partners_By

enum

NA

NA

NO_PRIORITIZATION

How to prioritize partners for the intervention, as long as they have been in a relationship longer than Minimum_Duration_Years. Possible values are:

NO_PRIORTIZATION

All partners are contacted.

CHOSEN_AT_RANDOM

Partners are randomly selected until Maximum_Partners have received the intervention.

LONGER_TIME_IN_RELATIONSHIP

Partners are sorted in descending order of the duration of the relationship. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

SHORTER_TIME_IN RELATIONSHIP

Partners are sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of the list until Maximum_Partners have received the intervention.

OLDER_AGE

Partners are sorted in descending order of their age. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

YOUNGER_AGE

Partners are sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

RELATIONSHIP_TYPE

Partners are sorted based on the order of relationship types defined in the Relationship_Types array. For example, “Relationship_Types” : [“MARITAL”, “INFORMAL”, “TRANSITORY”, “COMMERCIAL”], will prioritize marital first, then informal, then transitory, then commercial, with random selection between mulitple partners of the same type.

 
{
    "Prioritize_Partners_By": "LONGER_TIME_IN_RELATIONSHIP"
}

Relationship_Types

array of strings

NA

NA

NA

An array listing all possible relationship types for which partners can qualify for the intervention. Supported partnerships include TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL. If Prioritize_Partners_By is set to RELATIONSHIP_TYPE, then the order of these types is used. The array may not contain duplicates, and cannot be empty.

 
{
    "Relationship_Types": [
        "MARITAL",
        "INFORMAL",
        "TRANSITORY",
        "COMMERCIAL"
    ]
}
OutbreakIndividualTBorHIV (tuberculosis)

The OutbreakIndividualTBorHIV class extends OutbreakIndividual class and allows for specifying HIV or a specific strain of infection for TB.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Clade

integer

0

9

0

The clade ID (Clade) of the outbreak infection. Together with the genome ID (Genome) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Clade may range from 0 to Number_of_Clades-1.

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "Outbreak"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Genome

integer

0

16777215

0

The genome ID (Genome) of the outbreak infection. Together with the clade ID (Clade) they represent an infection as a unitary object. Values for Genome may range from -1 to 2Log2_Number_of_Genomes_per_Clade-1

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "OutbreakIndividualTBorHIV"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "OutbreakIndividualTBorHIV",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Ignore_Immunity

boolean

0

1

1

Individuals will be force-infected (with a specific strain) regardless of actual immunity level when set to true (1).

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Infection_Type": "TB",
        "Outbreak_Source": "PrevalenceIncrease",
        "Ignore_Immunity": 0,
        "class": "OutbreakIndividualTBorHIV"
    }
}

Incubation_Period_Override

integer

-1

2147480000

-1

The incubation period, in days, that infected individuals will go through before becoming infectious. This value overrides the incubation period set in the configuration file. Set to -1 to honor the configuration parameter settings.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Ignore_Immunity": 0,
        "Incubation_Period_Override": -1,
        "Infection_Type": "TB",
        "Outbreak_Source": "PrevalenceIncrease",
        "class": "OutbreakIndividualTBorHIV"
    }
}

Infection_Type

enum

NA

NA

HIV

Infection type. Possible values are:

HIV

HIV infection.

TB

TB infection.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Ignore_Immunity": 0,
        "Incubation_Period_Override": -1,
        "Infection_Type": "TB",
        "Outbreak_Source": "PrevalenceIncrease",
        "class": "OutbreakIndividualTBorHIV"
    }
}
EnvironmentalDiagnostic (typhoid)

The EnvironmentalDiagnostic intervention class identifies contaminated locations by sampling the environment, comparing the value to a threshold, and broadcasting either a positive or negative node event.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The likelihood that a positive measurement was made. If the contagion measurement is greater than the Sample_Threshold, a random number is drawn to determine if the detection was actually made.

 
{
    "Base_Sensitivity": 0.7,
    "Sample_Threshold": 0.85
}

Base_Specificity

float

0

1

1

The proportion of time that the environment being tested and without the condition receives a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then environments that do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Disqualifying_Properties

array of strings

NA

NA

NA

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": []
}

Environment_IP_Key_Value

string

NA

NA

NA

An IndividualProperty key:value pair that indicates a specific transmission pool, typically used to identify a location. If none is provided, the sample will be taken on the entire node.

 
{
    "Environment_IP_Key_Value": "Location:UP_RIVER"
}

Intervention_Name

string

NA

NA

EnvironmentalDiagnostic

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "Intervention_Name": "Downriver sample testing",
        "class": "EnvironmentalDiagnostic"
    }
}

Negative_Diagnostic_Event

string

NA

NA

“”

The event that will be broadcast to the node when the sample value is less than the threshold (e.g. the test is negative). If this is an empty string or set to NoTrigger, no event will be broadcast. See Event list for possible values, or create custom events using Custom_Node_Events.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnostic_Event": "Up_River_Clean"
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnostic_Event

string

NA

NA

“”

The event that will be broadcast to the node when the sample value is greater than the threshold (e.g. the test is positive). This cannot be an empty string or set to NoTrigger. See Event list for possible values, or create custom events using Custom_Node_Events.

 
{
    "Positive_Diagnostic_Event": "Up_River_Contagion_Found"
}

Sample_Threshold

float

0

3.40282e+38

0

The threshold that delineates a positive versus negative sampling result. If the sample is greater than the threshold, a positive finding will result; if the value is less than the threshold, it will be negative. This does not include values equal to the threshold so that the threshold can be set to zero; if the threshold is zero, the test is simply looking for any deposit in the transmission pool.

 
{
    "Sample_Threshold": 0.2
}
TyphoidCarrierDiagnostic (typhoid)

The TyphoidCarrierDiagnostic class extends SimpleDiagnostic class and allows for positive test diagnostic when an individual is a chronic typhoid carrier.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 1
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 1
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 10
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until diagnosis.

 
{
    "Days_To_Diagnosis": 2
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Base_Sensitivity": 0.92,
    "Base_Specificity": 0.85,
    "Enable_Is_Symptomatic": 1
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "Intervention_Name": "Typhoid diagnostic test",
        "class": "TyphoidCarrierDiagnostic"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "TyphoidCarrierDiagnostic",
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "Chronic_Carrier"
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 180,
        "class": "StandardInterventionDistributionEventCoordinator"
    },
    "Event_Name": "Diagnostic",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 2,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent"
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values, or create custom events using Custom_Individual_Events.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "TyphoidCarrierDiagnostic",
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "Chronic_Carrier"
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 180,
        "class": "StandardInterventionDistributionEventCoordinator"
    },
    "Event_Name": "Diagnostic",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 2,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent"
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated.

 
{
    "Treatment_Fraction": 1
}
TyphoidVaccine (typhoid)

The TyphoidVaccine intervention class identifies contaminated locations by sampling the environment, comparing the value to a threshold, and broadcasting either a positive or negative node event.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Changing_Effect

JSON object

NA

NA

NA

A highly configurable effect that changes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Intervention_Config": {
        "Changing_Effect": {
            "Durability_Map": {
                "Times": [
                    0,
                    10,
                    11,
                    20,
                    21,
                    26,
                    27,
                    33,
                    34,
                    40
                ],
                "Values": [
                    0,
                    0,
                    1,
                    1,
                    0,
                    0,
                    1,
                    1,
                    0,
                    0
                ]
            },
            "Expire_At_Durability_Map_End": 1,
            "Initial_Effect": 1,
            "class": "WaningEffectMapLinear"
        },
        "Effect": 1,
        "Mode": "Dose",
        "Target_Demographic": "Everyone",
        "class": "TyphoidVaccine"
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Effect

float

0

1

1

The efficacy of the Typhoid vaccine intervention. For example, a value of 1 would be 100 percent efficacy for all targeted nodes within the intervention.

 
{
    "Intervention_Config": {
        "Changing_Effect": {
            "Durability_Map": {
                "Times": [
                    0,
                    10,
                    11,
                    20,
                    21,
                    26,
                    27,
                    33,
                    34,
                    40
                ],
                "Values": [
                    0,
                    0,
                    1,
                    1,
                    0,
                    0,
                    1,
                    1,
                    0,
                    0
                ]
            },
            "Expire_At_Durability_Map_End": 1,
            "Initial_Effect": 1,
            "class": "WaningEffectMapLinear"
        },
        "Effect": 1,
        "Mode": "Dose",
        "Target_Demographic": "Everyone",
        "class": "TyphoidVaccine"
    }
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "TyphoidVaccine",
        "Intervention_Name": "Country-wide vaccination campaign"
    }
}

Mode

enum

NA

NA

Shedding

The mode of contact transmission of typhoid targeted by the intervention. Possible values are:

  • Dose (disease acquisition)

    Reduces the amount of contagion an individual is exposed to per exposure event, by a proportion. This is similar to setting Vaccine_Type to AcquisitionBlocking when using SimpleVaccine.

  • Exposures (disease acquisition)

    Reduces the number of exposures to pathogen by a proportion. This is similar to setting Vaccine_Type to AcquisitionBlocking when using SimpleVaccine.

  • Shedding (disease transmission)

    Reduces the amount of contagion shed if a vaccinated individual is infected. This is similar to setting Vaccine_Type to TransmissionBlocking when using SimpleVaccine.

 
{
    "Intervention_Config": {
        "Changing_Effect": {
            "Durability_Map": {
                "Times": [
                    0,
                    10,
                    11,
                    20,
                    21,
                    26,
                    27,
                    33,
                    34,
                    40
                ],
                "Values": [
                    0,
                    0,
                    1,
                    1,
                    0,
                    0,
                    1,
                    1,
                    0,
                    0
                ]
            },
            "Expire_At_Durability_Map_End": 1,
            "Initial_Effect": 1,
            "class": "WaningEffectMapLinear"
        },
        "Effect": 1,
        "Mode": "Dose",
        "Target_Demographic": "Everyone",
        "class": "TyphoidVaccine"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}
TyphoidWASH (typhoid)

The TyphoidWASH intervention class acts on exposure through either the contact contagion population or the environmental contagion population in the simulation. The intervention can be configured to reduce either exposure dose or exposure frequency for each route, simulating effects of water, sanitation, and hygiene (WASH) interventions.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Changing_Effect

JSON object

NA

NA

NA

A highly configurable effect that changes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Intervention_Config": {
        "Changing_Effect": {
            "Expire_At_Durability_Map_End": 1,
            "Initial_Effect": 1,
            "class": "WaningEffectConstant"
        },
        "Effect": 1,
        "Mode": "Exposures",
        "Use_Property_Targeting": 0,
        "class": "TyphoidWASH"
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Effect

float

0

1

1

The efficacy of the TyphoidWASH intervention. For example, a value of 1 would be 100 percent efficacy for all targeted nodes within the intervention.

 
{
    "Intervention_Config": {
        "Changing_Effect": {
            "Expire_At_Durability_Map_End": 1,
            "Initial_Effect": 1,
            "class": "WaningEffectConstant"
        },
        "Effect": 1,
        "Mode": "Exposures",
        "Use_Property_Targeting": 0,
        "class": "TyphoidWASH"
    }
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "Intervention_Name": "TyphoidWASH intervention campaign",
        "class": "TyphoidWASH"
    }
}

Mode

enum

NA

NA

Shedding

The mode of environmental or contact transmission of typhoid targeted by the intervention. Possible values are:

  • Dose (disease acquisition)

    Reduces the amount of contagion an individual is exposed to per exposure event, by a proportion.

  • Exposures (disease acquisition)

    Reduces the number of exposures to pathogen by a proportion.

  • Shedding (disease transmission)

    Reduces the amount of contagion shed if a vaccinated individual is infected.

 
{
    "Intervention_Config": {
        "Mode": "Exposures",
        "Effect": 1,
        "Use_Property_Targeting": 0,
        "Changing_Effect": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 1,
            "Expire_At_Durability_Map_End": 1
        },
        "class": "TyphoidWASH"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Targeted_Individual_Properties

string

NA

NA

NA

Individual Property key-value pairs to be targeted (optional).

 
{
    "Intervention_Config": {
        "Mode": "Exposures",
        "Effect": 1,
        "Use_Property_Targeting": 1,
        "Changing_Effect": {
            "class": "WaningEffectMapLinear",
            "Initial_Effect": 1,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [
                    0,
                    100,
                    200,
                    300,
                    400,
                    500
                ],
                "Values": [
                    0,
                    1,
                    1,
                    1,
                    0,
                    1
                ]
            }
        },
        "class": "TyphoidWASH",
        "Targeted_Individual_Properties": "Risk:Target_Demographic"
    }
}

Use_Property_Targeting

boolean

0

1

1

Set to 1 (true) – or omit – if you want to use the Targeted_Individual_Property parameter to limit the effect of this intervention to just certain individuals. Set to 0 to apply effect to everyone.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "Mode": "Shedding",
            "Use_Property_Targeting": 0,
            "Effect": 1.0,
            "Changing_Effect": {
                "class": "WaningEffectConstant",
                "Initial_Effect": 1.0,
                "Expire_At_Durability_Map_End": 1
            },
            "class": "TyphoidWASH"
        },
        "class": "StandardInterventionDistributionEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 10,
    "class": "CampaignEvent"
}
New campaign parameters (Beta)

Note

These campaign classes and associated parameters are currently in beta release and have not yet been fully tested.

BroadcastCoordinatorEvent (generic)

The BroadcastCoordinatorEvent coordinator class broadcasts the event you specify. This can be used with the campaign class, SurveillanceEventCoordinator, that can monitor and listen for events received from BroadcastCoordinatorEvent and then perform an action based on the broadcasted event. You can also use this for the reporting of the broadcasted events by setting the configuraton parameters, Report_Node_Event_Recorder and Report_Surveillance_Event_Recorder, which listen to events to be recorded.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The name of the event to be broadcast. This event must be set in the Custom_Coordinator_Events configuration parameter. This cannot be assigned an empty string for the event.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_1",
        "Cost_To_Consumer": 10,
        "Broadcast_Event": "Coordinator_Event_1"
    }
}

Coordinator_Name

string

NA

NA

NA

The unique identifying coordinator name, which is useful with the output report, ReportCoordinatorEventRecorder.csv.

 
{
    "class": "CampaignEvent",
    "Start_Day": 25,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordinator_3",
        "Cost_To_Consumer": 30,
        "Broadcast_Event": "Coordinator_Event_3"
    }
}

Cost_To_Consumer

float

0

3.40282e+38

0

The unit cost of broadcasting the event.

 
{
    "class": "CampaignEvent",
    "Start_Day": 15,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_2",
        "Cost_To_Consumer": 20,
        "Broadcast_Event": "Coordinator_Event_2"
    }
}
BroadcastNodeEvent (generic)

The BroadcastNodeEvent coordinator class broadcasts node events. This can be used with the campaign class, SurveillanceEventCoordinator, that can monitor and listen for events received from BroadcastNodeEvent and then perform an action based on the broadcasted event. You can also use this for the reporting of the broadcasted events by setting the configuraton parameters, Report_Node_Event_Recorder and Report_Surveillance_Event_Recorder, which listen to events to be recorded.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

UNINITIALIZED STRING

The name of the node event to broadcast. This event must be set in the Custom_Node_Events configuration parameter. Note that there are no built-in node events for malaria.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1
        ]
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
            "class": "BroadcastNodeEvent",
            "Cost_To_Consumer": 10,
            "Broadcast_Event": "Node_Event_1"
        }
    }
}

Cost_To_Consumer

float

0

999999

0

The unit cost of the intervention campaign that will be assigned to the specified nodes, as configured under Nodeset_Config.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1
        ]
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
            "class": "BroadcastNodeEvent",
            "Cost_To_Consumer": 10,
            "Broadcast_Event": "Node_Event_1"
        }
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

BroadcastNodeEvent

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BroadcastNodeEvent",
        "Intervention_Name": "Mosquito coil repellent"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}
DelayEventCoordinator (generic)

The DelayEventCoordinator coordinator class insert delays into coordinator event chains. This campaign event is typically used with BroadcastCoordinatorEvent to broadcast events after the delays.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Coordinator_Name

string

NA

NA

DelayEventCoordinator

The unique identifying coordinator name, which is useful with the output report, ReportCoordinatorEventRecorder.csv.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Delay_Complete_Event

string

NA

NA

NA

The delay completion event to be included in the ReportCoordinatorEventRecorder.csv output report, upon completion of the delay period.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Distribution": "GAUSSIAN_DURATION",
        "Delay_Period_Mean": 25,
        "Delay_Period_Std_Dev": 5,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Delay_Period_Constant

float

0

3.40282E+38

-1

The delay period to use for all interventions, in days, when Delay_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Delay_Period_Constant": 8
}

Delay_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Delay_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Delay_Period_Max and Delay_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Delay_Period_Gaussian_Mean and Delay_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Delay_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Delay_Period_Kappa and Delay_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Delay_Period_Log_Normal_Mu and Delay_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Delay_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Delay_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Delay_Period_Mean_1, Delay_Period_Mean_2, and Delay_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Exponential

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Exponential": 4.25
}

Delay_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Max

float

0

3.40282E+38

-1

The maximum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Min

float

0

3.40282E+38

-1

The minimum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Peak_2_Value

float

0

3.40282E+38

-1

The delay period value, in days, to assign to the remaining interventions when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "POISSON_DISTRIBUTION",
    "Delay_Period_Poisson_Mean": 5
}

Delay_Period_Proportion_0

float

0

1

-1

The proportion of interventions to assign a value of zero delay when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Proportion_1

float

0

1

-1

The proportion of interventions in the first exponential distribution when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Duration

float

-1

3.40282e+38

-1

The number of days from when the delay event coordinator was created by the campaign event. Once the number of days has passed, the delay event coordinator will unregister for events and expire. The default value of ‘-1’ = never expire.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent"
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The start trigger event condition list contains events defined in the Custom_Coordinator_Events config parameter that will trigger to start a new delay. If the delay event coordinator has already been triggered and is currently waiting for the duration of a delay, it will then ignore a new delay event. The list cannot be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The stop trigger event condition list contains events defined in the Custom_Coordinator_Events config parameter that will trigger to stop a delay period, but does not stop the delay event coordinator. The event is not broadcast.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}
SurveillanceEventCoordinator (generic)

The SurveillanceEventCoordinator coordinator class listens for and detects events happening and then responds with broadcasted events when a threshold has been met. This campaign event is typically used with other classes, such as BroadcastCoordinatorEvent, TriggeredEventCoordinator, and DelayEventCoordinator.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Action_List

array of JSON objects

NA

NA

NA

A list of possible actions to take if a particular threshold is met. An action is taken when the specified threshold value is less than the number of incidence counted. If there are multiple actions listed then the action with the highest threshold value, that is also less than the number of incidence counted, is selected. The list cannot be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Coordinator_Name

string

NA

NA

TriggeredEventCoordinator

The unique identifying coordinator name, which is useful with the output report, ReportSurveillanceEventRecorder.csv.

 
{
    "class": "CampaignEvent",
    "Start_Day": 1,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "SurveillanceEventCoordinator",
        "Coordinator_Name": "ACF_Counter",
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Type": "PERIODIC",
            "Counter_Period": 14,
            "Counter_Event_Type": "NODE",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ],
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1
        },
        "Responder": {
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT",
            "Action_List": [
                {
                    "Threshold": 5,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_2"
                },
                {
                    "Threshold": 2,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_4"
                }
            ]
        }
    }
}

Counter_Event_Type

enum

NA

NA

INDIVIDUAL

Type of events that can be included in Trigger_Condition_List. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Counter_Period

float

1

10000

1

When Counter_Type is set to PERIODIC, this is the counter period (in days).

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Counter_Type

enum

NA

NA

PERIODIC

Counter type used for surveillance of events. The counter is triggered by events in Start_Trigger_Condition_List and the counter stops when it receives an event in Stop_Trigger_Condition_List or the listening duration expires. Possible values are:

PERIODIC

Once triggered, events are counted during the period (in days) as set in Counter_Period. At the end of the period, the counter will notify Responder with the data accumulated and then start listening again, continuing forever until it is stopped or the duration expires. For example, if the listening duration is 45 days, Counter_Period is 30, and the counter is triggered on day 20, it will never complete the counter period and trigger the responder.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that are counted.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Duration

float

-1

3.40282e+38

-1

The number of days from when the surveillance event coordinator was created by the campaign event. Once the number of days has passed, the delay event coordinator will unregister for events and expire. The default value of ‘-1’ = never expire.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Event_Type

enum

NA

NA

INDIVIDUAL

The type of event to be broadcast. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Incidence_Counter

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the conditions and parameters that must be met for an incidence to be counted. Some of the values are specified in the following parameters: Counter_Type, Counter_Period, Counter_Event_Type, Trigger_Condition_List, Node_Property_Restrictions, Property_Restrictions_Within_Node.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Percentage_Events_To_Count

array of strings

NA

NA

NA

When Threshold_Type equals PERCENTAGE_EVENTS then Percentage_Events_To_Count lists the events that will be counted for the denominator which will then be used with the specified event for Trigger_Condition_List counted for the numerator.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": -1,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 30,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Node_Property_Restrictions": [],
            "Property_Restrictions_Within_Node": [],
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Positive_Event_Node"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 0.5
                }
            ],
            "Percentage_Events_To_Count": [
                "Negative_Event_Node",
                "Positive_Event_Node"
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "PERCENTAGE_EVENTS"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Geographic": "URBAN",
            "Risk": "HIGH"
        },
        {
            "Geographic": "URBAN",
            "Risk": "MEDIUM"
        }
    ]
}

Responded_Event

string

NA

NA

“”

A coordinator event, defined in Custom_Coordinator_Events, that is broadcast if Responder responded. More specifically, at the completion of a counting period, if an action is selected, the action events are broadcast and then the Responded_Event is also broadcast. This allows other event coordinators to react to the action events being broadcast.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Responder

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the threshold type, values, and the actions to take when the specified conditions and parameters have been met, as configured in Incidence_Counter. Some of the values are specified in the following parameters:

  • Action_List

  • Event_To_Broadcast

  • Threshold_Type

  • Threshold

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger event list, as specified in the Custom_Coordinator_Events config parameter, that will start Incidence_Counter counting events. The surveillance event coordinator will keep counting and responding until it gets a stop event, as defined in Stop_Trigger_Condition_List, or the duration of the surveillance event coordinator has expired, as defined in Duration. The list cannot be empty.

 
{
    "class": "CampaignEvent",
    "Start_Day": 1,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "SurveillanceEventCoordinator",
        "Coordinator_Name": "ACF_Counter",
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Type": "PERIODIC",
            "Counter_Period": 14,
            "Counter_Event_Type": "NODE",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ],
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1
        },
        "Responder": {
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT",
            "Action_List": [
                {
                    "Threshold": 5,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_2"
                },
                {
                    "Threshold": 2,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_4"
                }
            ]
        }
    }
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The broadcast event list, as specified in the Custom_Coordinator_Events config parameter, that will stop Incidence_Counter counting events. The coordinator can start counting again if it receives a start trigger event. The list can be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Female"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), only individuals that currently reside in their ‘home’ node will be counted.

 
{
    "Target_Residents_Only": 1
}

Threshold

float

0

3.40282e+38

0

The COUNT or PERCENTAGE, as configured with Threshold_Type, threshold value that must be met before and action from Action_List will be considered.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Threshold_Type

enum

NA

NA

COUNT

Threshold type to indicate how Responder handles the count of events from Incidence_Counter and the thresholds in Action_List. Possible values are:

COUNT

A raw count of events. Also, with COUNT, setting the x_Base_Population configuration parameter can affect the number count by changing the population but it could be very indirect.

PERCENTAGE

Counts the number of individuals that meet the restrictions and then to divide the total number of events by this number. Note that it is possible for an individual to emit an event that might not be counted in the denominator if their demographic restriction attributes changed between the time of the emitted event and the time the denominator was counted.

PERCENTAGE_EVENTS

Percentage_Events_To_Count lists the events that will be counted for the denominator, which will then be used with the specified event for Trigger_Condition_List to be counted for the numerator.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Trigger_Condition_List

array of strings

NA

NA

NA

The list of events to count.The list cannot be empty. The type of events contained in the list is determined by Counter_Event_Type. Depending upon the type, the events must be defined in one of the following configuration parameters:

  • Custom_Coordinator_Events

  • Custom_Individual_Events

  • Custom_Node_Events

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}
TriggeredEventCoordinator (generic)

The TriggeredEventCoordinator coordinator class listens for trigger events, begins a series of repetitions of intervention distributions, and then broadcasts an event upon completion. This campaign event is typically used with other classes that broadcast and distribute events, such as BroadcastCoordinatorEvent, DelayEventCoordinator, and SurveillanceEventCoordinator.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Completion_Event

array of strings

NA

NA

NA

The completion event list that will be broadcast every time the triggered event coordinator completes a set of repetitions. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "class": "TriggeredEventCoordinator",
        "Coordinator_Name": "1n2_Vaccinator",
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Number_Repetitions": 1,
        "Timesteps_Between_Repetitions": 1,
        "Duration": -1,
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.05,
        "Intervention_Config": {
            "class": "SimpleVaccine",
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "class": "WaningEffectBox",
                "Initial_Effect": 0.59,
                "Box_Duration": 730
            }
        },
        "Completion_Event": "Done_Vaccinating_1n2"
    }
}

Coordinator_Name

string

NA

NA

TriggeredEventCoordinator

The unique identifying coordinator name used to identify the different coordinators in reports.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Duration

float

-1

3.40282e+38

-1

The time period (in days) that the triggered event coordinator is active before it expires. Once the specified duration has been reached the coordinator will expire whether or not it is in the middle of a set of repetitions. The value of -1 (default) equals to never expire.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the intervention to be distributed by this event coordinator.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information. You can specify AND and OR combinations of key:value pairs with this parameter.

The following configuration restrictions the intervention to nodes that are urban and high risk or have had the first round treatment and are low risk.

{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_3n4",
        "Coordinator_Name": "3n4_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 2,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Node_Property_Restrictions": [
            {
                "Place": "Urban",
                "Risk": "High"
            },
            {
                "InterventionStatus": "FirstRound",
                "Risk": "Low"
            }
        ],
        "Number_Repetitions": 3,
        "Property_Restrictions_Within_Node": [],
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_3n4"
        ],
        "Stop_Trigger_Condition_List": [
            "Stop_Vaccinating_3n4"
        ],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 10,
        "class": "TriggeredEventCoordinator"
    }
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_3n4",
        "Coordinator_Name": "3n4_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 2,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 3,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_3n4"
        ],
        "Stop_Trigger_Condition_List": [
            "Stop_Vaccinating_3n4"
        ],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 10,
        "class": "TriggeredEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Geographic": "URBAN",
            "Risk": "HIGH"
        },
        {
            "Geographic": "URBAN",
            "Risk": "MEDIUM"
        }
    ]
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger condition event list that when heard will start a new set of repetitions for the triggered event coordinator. The list cannot be empty. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger condition event list that when heard will stop any repetitions for the triggered event coordinator until a start trigger condition event list is received. The list can be empty. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Female"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}
Deprecated configuration parameters

Base_Population_Scale_Factor has been renamed to x_Base_Population, which is grouped together with the other scale factor parameters beginning with x_. The functional remains the same. Enable_Demographics_Gender has been deprecated. Animal_Reservoir_Type has been replaced with Enable_Infectivity_Reservoir.

The following configuration parameters have been deprecated as a result of the refactoring of distribution parameters for better consistency across the configuration and campaign files.

Parameter

Incubation_Period_Log_Mean

Incubation_Period_Log_Width

Infectious_Period_Mean

Infectious_Period_Std_Dev
Deprecated campaign parameters

The following campaign parameters have been deprecated as a result of the refactoring of distribution parameters for better consistency across the configuration and campaign files.

Parameter

BitingRisk Constant

BitingRisk Risk_Distribution_Type

BitingRisk Exponential_Mean

BitingRisk Gaussian_Mean

BitingRisk Gaussian_Std_Dev

BitingRisk Uniform_Max

BitingRisk Uniform_Min

CommunityHealthWorkerEventCoordinator Initial_Amount

CommunityHealthWorkerEventCoordinator Initial_Amount_Distribution_Type

CommunityHealthWorkerEventCoordinator Initial_Amount_Mean

CommunityHealthWorkerEventCoordinator Initial_Amount_Std_Dev

DelayedIntervention Delay_Distribution

DelayedIntervention Delay_Period

DelayedIntervention Delay_Period_Mean

DelayedIntervention Delay_Period_Scale

DelayedIntervention Delay_Period_Shape

DelayedIntervention Delay_Period_Std_Dev

DelayEventCoordinator Delay_Distribution

DelayEventCoordinator Delay_Period

DelayEventCoordinator Delay_Period_Mean

DelayEventCoordinator Delay_Period_StdDev

HIVDelayedIntervention Delay_Distribution

HIVDelayedIntervention Delay_Period

HIVDelayedIntervention Delay_Period_Mean

HIVDelayedIntervention Delay_Period_Scale

HIVDelayedIntervention Delay_Period_Shape

HIVDelayedIntervention Delay_Period_Std_Dev

HIVMuxer Delay_Distribution

HIVMuxer Delay_Period

HIVMuxer Delay_Period_Mean

HIVMuxer Delay_Period_Scale

HIVMuxer Delay_Period_Shape

HIVMuxer Delay_Period_Std_Dev

MigrateFamily Duration_At_Node_Distribution_Type

MigrateFamily Duration_At_Node_Exponential_Period

MigrateFamily Duration_At_Node_Fixed

MigrateFamily Duration_At_Node_Gausian_Mean

MigrateFamily Duration_At_Node_Gausian_StdDev

MigrateFamily Duration_At_Node_Uniform_Max

MigrateFamily Duration_At_Node_Uniform_Min

MigrateFamily Duration_Before_Leaving_Distribution_Type

MigrateFamily Duration_Before_Leaving_Exponential_Period

MigrateFamily Duration_Before_Leaving_Fixed

MigrateFamily Duration_Before_Leaving_Gausian_Mean

MigrateFamily Duration_Before_Leaving_Gausian_StdDev

MigrateFamily Duration_Before_Leaving_Uniform_Max

MigrateFamily Duration_Before_Leaving_Uniform_Min

MigrateIndividuals Duration_At_Node_Distribution_Type

MigrateIndividuals Duration_At_Node_Exponential_Period

MigrateIndividuals Duration_At_Node_Fixed

MigrateIndividuals Duration_At_Node_Gausian_Mean

MigrateIndividuals Duration_At_Node_Gausian_StdDev

MigrateIndividuals Duration_Before_Leaving_Distribution_Type

MigrateIndividuals Duration_Before_Leaving_Exponential_Period

MigrateIndividuals Duration_Before_Leaving_Fixed

MigrateIndividuals Duration_Before_Leaving_Gausian_Mean

MigrateIndividuals Duration_Before_Leaving_Gausian_StdDev

MigrateIndividuals Duration_Before_Leaving_Uniform_Max

MigrateIndividuals Duration_Before_Leaving_Uniform_Min

MigrateIndividuals Duration_At_Node_Uniform_Max

MigrateIndividuals Duration_At_Node_Uniform_Min

UsageDependentBednet Expiration_Distribution_Type

UsageDependentBednet Expiration_Percentage_Period_1

UsageDependentBednet Expiration_Period

UsageDependentBednet Expiration_Period_1

UsageDependentBednet Expiration_Period_2

UsageDependentBednet Expiration_Period_Mean

UsageDependentBednet Expiration_Period_Std_Dev

EMOD v2.18

The EMOD v2.18 release includes many new features for all supported simulation types. In particular, the TB_SIM simulation type has been deprecated and replaced with TBHIV_SIM, which does not include HIV transmission but adds the ability to model the effect of HIV coinfection on the spread of TB.

New configuration parameters

To view all available configuration parameters, see Configuration parameters.

New campaign parameters

The following campaign classes are new for the Generic model and can be used in all other models:

IncidenceEventCoordinator (generic)

The IncidenceEventCoordinator coordinator class distributes interventions based on the number of events counted over a period of time.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Action_List

array of JSON objects

NA

NA

NA

List (array) of JSON objects, including the values specified in the following parameters: Threshold, Event_Type, Event_To_Broadcast.

 
{
    "Action_List": [
        {
            "Event_To_Broadcast": "Action_Event_1",
            "Event_Type": "COORDINATOR",
            "Threshold": 20
        },
        {
            "Event_To_Broadcast": "Action_Event_2",
            "Event_Type": "COORDINATOR",
            "Threshold": 30
        }
    ],
    "Threshold_Type": "COUNT"
}

Count_Events_For_Num_Timesteps

integer

1

2.15E+00

1

If set to true (1), then the waning effect values, as specified in the Effect_List list of objects for the WaningEffectCombo classes, are added together. If set to false (0), the waning effect values are multiplied. The resulting waning effect value cannot be greater than 1.

 
{
    "Incidence_Counter": {
        "Count_Events_For_Num_Timesteps": 5,
        "Trigger_Condition_List": [
            "PropertyChange"
        ],
        "Node_Property_Restrictions": [
            {
                "Risk": "HIGH"
            }
        ],
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.6,
        "Property_Restrictions_Within_Node": [
            {
                "Accessibility": "YES"
            }
        ]
    }
}

Event_To_Broadcast

string

NA

NA

NA

The action event to occur when the specified trigger value in the Threshold parameter is met. At least one action must be defined for Event_To_Broadcast. The events contained in the list can be built-in events (see Event list for possible events).

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Event_Type

enum

NA

NA

INDIVIDUAL

The type of event to be broadcast. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Action_List": [
        {
            "Event_To_Broadcast": "Action_Event_1",
            "Event_Type": "COORDINATOR",
            "Threshold": 20
        },
        {
            "Event_To_Broadcast": "Action_Event_2",
            "Event_Type": "COORDINATOR",
            "Threshold": 30
        }
    ],
    "Threshold_Type": "COUNT"
}

Incidence_Counter

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the conditions and parameters that must be met for an incidence to be counted. Some of the values are specified in the following parameters: Count_Events_For_Num_Timesteps, Trigger_Condition_List, Node_Property_Restrictions.

 
{
    "Incidence_Counter": {
        "Count_Events_For_Num_Timesteps": 5,
        "Trigger_Condition_List": [
            "PropertyChange"
        ],
        "Node_Property_Restrictions": [
            {
                "Risk": "HIGH"
            }
        ],
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.6,
        "Property_Restrictions_Within_Node": [
            {
                "Accessibility": "YES"
            }
        ]
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information. You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "class": "IncidenceEventCoordinator",
    "Number_Repetitions": 3
}

Responder

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the threshold type, values, and the actions to take when the specified conditions and parameters have been met, as configured in the Incidence_Counter parameter. Some of the values are specified in the following parameters:

  • Threshold_Type

  • Action_List

  • Threshold

  • Event_To_Broadcast

 
{
    "Responder": {
        "Threshold_Type": "COUNT",
        "Action_List": [
            {
                "Threshold": 5,
                "Event_To_Broadcast": "Action_Event_1"
            },
            {
                "Threshold": 10,
                "Event_To_Broadcast": "Action_Event_2"
            }
        ]
    }
}

Threshold

float

0

3.40E+03

0

The threshold value that triggers the specified action for the Event_To_Broadcast parameter. When you use the Threshold parameter you must also use the Event_To_Broadcast parameter.

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Threshold_Type

enum

NA

NA

COUNT

Threshold type. Possible values are:

  • COUNT

  • PERCENTAGE.

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Timesteps_Between_Repetitions

integer

-1

1000

-1

The repetition interval.

 
{
    "class": "IncidenceEventCoordinator",
    "Number_Repetitions": 3,
    "Timesteps_Between_Repetitions": 6
}

Trigger_Condition_List

array of strings

NA

NA

NA

A list of events that will trigger an intervention.

 
{
    "Trigger_Condition_List": [
        "NewClinicalCase",
        "NewSevereCase"
    ]
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}
MultiNodeInterventionDistributor (generic)

The MultiNodeInterventionDistributor intervention class distributes multiple node-level interventions when the distributor only allows specifying one intervention.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

MultiNodeInterventionDistributor

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiNodeInterventionDistributor",
        "Intervention_Name": "Country-wide vaccination"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Intervention_List

array of JSON objects

NA

NA

NA

A list of nested JSON objects for the multi-node-level interventions to be distributed by this intervention.

 
{
    "Intervention_Config": {
        "class": "MultiNodeInterventionDistributor",
        "Node_Intervention_List": [
            {
                "class": "SpaceSpraying",
                "Cost_To_Consumer": 1.0,
                "Habitat_Target": "ALL_HABITATS",
                "Spray_Kill_Target": "SpaceSpray_Indoor",
                "Killing_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                },
                "Reduction_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                }
            },
            {
                "class": "NodePropertyValueChanger",
                "Target_NP_Key_Value": "InterventionStatus:RECENT_SPRAY",
                "Daily_Probability": 1.0,
                "Maximum_Duration": 0,
                "Revert": 90
            }
        ]
    }
}
WaningEffectCombo (generic)

The WaningEffectCombo class is used within individual-level interventions and allows for specifiying a list of effects when the intervention only has one WaningEffect defined. These effects can be added or multiplied.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Add_Effects

boolean

0

1

0

The Add_Effects parameter allows you to combine multiple effects from the waning effect classes. If set to true (1), then the waning effect values from the different waning effect objects are added together. If set to false (0), the waning effect values are multiplied. The resulting waning effect value must be greater than 1.

 
{
    "class": "WaningEffectCombo",
    "Add_Effects": 1,
    "Expires_When_All_Expire": 0,
    "Effect_List": [
        {
            "class": "WaningEffectMapLinear",
            "Initial_Effect": 1.0,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [
                    0.0,
                    1.0,
                    2.0
                ],
                "Values": [
                    0.2,
                    0.4,
                    0.6
                ]
            }
        },
        {
            "class": "WaningEffectBox",
            "Initial_Effect": 0.5,
            "Box_Duration": 5.0
        }
    ]
}

Effect_List

array of JSON objects

NA

NA

NA

A list of nested JSON parameters to indicate how the intervention efficacy wanes over time.

 
{
    "class": "WaningEffectCombo",
    "Add_Effects": 1,
    "Expires_When_All_Expire": 0,
    "Effect_List": [
        {
            "class": "WaningEffectMapLinear",
            "Initial_Effect": 1.0,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [
                    0.0,
                    1.0,
                    2.0
                ],
                "Values": [
                    0.2,
                    0.4,
                    0.6
                ]
            }
        },
        {
            "class": "WaningEffectBox",
            "Initial_Effect": 0.5,
            "Box_Duration": 5.0
        }
    ]
}

Expires_When_All_Expire

boolean

0

1

0

If set to true (1), then all of the effects, as specified in the Effect_List parameter, must expire for the efficacy of the intervention to expire. If set to false (0), then the efficacy of the intervention will expire as soon as one of the parameters expires.

 
{
    "class": "WaningEffectCombo",
    "Add_Effects": 1,
    "Expires_When_All_Expire": 0,
    "Effect_List": [
        {
            "class": "WaningEffectMapLinear",
            "Initial_Effect": 1.0,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [
                    0.0,
                    1.0,
                    2.0
                ],
                "Values": [
                    0.2,
                    0.4,
                    0.6
                ]
            }
        },
        {
            "class": "WaningEffectBox",
            "Initial_Effect": 0.5,
            "Box_Duration": 5.0
        }
    ]
}

The following campaign classes are new for the Malaria model:

AdherentDrug (malaria)

The AdherentDrug class extends AntiMalarialDrug class and allows for incorporating different patterns of adherence to taking the drug.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Adherence_Config

JSON object

NA

NA

NA

Configuration for the probability of taking a dose of the specified anti-malarial. Use a waning effect class, Waning effect classes, to specify how this probability changes over time.

 
{
    "Adherence_Config": {
        "class": "WaningEffectMapCount",
        "Initial_Effect": 1.0,
        "Durability_Map": {
            "Times": [
                1.0,
                2.0,
                3.0,
                4.0
            ],
            "Values": [
                0.1,
                0.1,
                0.1,
                0.1
            ]
        }
    }
}

Cost_To_Consumer

float

0

99999

10

The unit cost per drug (unamortized).

 
{
    "Cost_To_Consumer": 10
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Dose_Interval

float

0

1000

1

The number of days to wait between the doses, defined in the Doses parameter.

 
{
    "Dose_Interval": 10
}

Doses

array of strings

NA

NA

NA

This is a two dimensional array of the drug names defined in the config. parameter Malaria_Drug_Params. Each inner array defines the drugs to be taken for a single dose. The number of doses is determined by the number of inner arrays. An empty dose is allowed and counts as if the person did not take any doses that day. If multiple pills of the same drug are taken in the same dose, that drug name can be specified multiple times.

 
{
    "Doses": [
    ["TestDrugA", "TestDrugB"],
    ["TestDrugA"],
    ["TestDrugA", "TestDrugB"],
    ["TestDrugB"]
]
}

Intervention_Name

string

NA

NA

AdherentDrug

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "AdherentDrug",
        "Intervention_Name": "Isoniazid with mediocre adherence"
    }
}

Max_Dose_Consideration_Duration

float

1.0/24.0 (1hr)

3.40E+038

3.40E+038

The maximum number of days that an individual will consider taking the doses of the drug.

 
{
    "class": "AdherentDrug",
    "Cost_To_Consumer": 1,
    "Drug_Type": "TestDrug",
    "Dosing_Type": "FullTreatmentCourse",
    "Adherence_Config": {
        "class": "WaningEffectMapCount",
        "Initial_Effect": 1.0,
        "Durability_Map": {
            "Times": [
                1.0,
                2.0,
                3.0
            ],
            "Values": [
                1.0,
                0.0,
                1.0
            ]
        }
    },
    "Non_Adherence_Options": [
        "NEXT_DOSAGE_TIME"
    ],
    "Non_Adherence_Distribution": [
        1.0
    ],
    "Max_Dose_Consideration_Duration": 4,
    "Took_Dose_Event": "NewClinicalCase"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Non_Adherence_Distribution

array of floats

0

1

0

The non adherence probability value(s) assigned to the corresponding options in Non_Adherence_Options. The sum of non adherence distribution values must equal a total of 1.

 
{
    "Non_Adherence_Distribution": [
        0.7,
        0.3
    ]
}

Non_Adherence_Options

array of eunums

NA

NA

NEXT_UPDATE

Defines the action the person takes if they do not take a particular dose, are not adherent. Possible values are:

NEXT_UPDATE

The person does not take the dose during this update, but will consider taking during the next update (and may not take the dose then). If this person is infected, the time to the next update depends on Infection_Updates_Per_Timestep.

LOST_TAKE_NEXT

The person lost the dose and so takes the next dose in the pill pack (so the total number of pills is reduced).

NEXT_DOSAGE_TIME

The person missed a dose and waits until the next dosage time to take the pill, in order to remain on the prescribed dosage schedule.

STOP

The person decides to stop taking the pills (or has lost the pill pack). Pills taken prior to STOP will have an effect, no remaining pills will be taken.

 
{
    "AD_Non_Adherence_Options": [
        "NEXT_DOSAGE_TIME",
        "NEXT_UPDATE"
    ]
}

Took_Dose_Event

string

NA

NA

“”

This event is broadcast each time a person takes a dose from the pill pack.

 
{
    "Took_Dose_Event": "TakingDrug"
}
BitingRisk (malaria, vector)

The BitingRisk class is used with individual-level interventions and allows for adjusting the relative risk of being bitten by a vector.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

BitingRisk

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BitingRisk",
        "Intervention_Name": "Relative biting risk with bednet usage"
    }
}

New_Property_Value

string

NA

NA

UNINITIALIZED STRING

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Risk_Constant

float

0

3.40282E+38

6

The risk to use for all individuals when Risk_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Risk_Distribution": "CONSTANT_DISTRIBUTION",
    "Risk_Constant": 8
}

Risk_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the relative risk of being bitten by a mosquito to each individual. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Risk_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Risk_Max and Risk_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Risk_Gaussian_Mean and Risk_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Risk_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Risk_Kappa and Risk_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and width. Set Risk_Log_Normal_Mean and Risk_Log_Normal_Width.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Risk_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Risk_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Risk_Mean_1, Risk_Mean_2, and Risk_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "WEIBULL_DISTRIBUTION",
    "Risk_Kappa": 0.9,
    "Risk_Lambda": 1.5
}

Risk_Exponential

float

0

3.40282E+38

-1

The mean of the biting risk when Risk_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Risk_Exponential": 4.25
}

Risk_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the biting risk when Risk_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Risk_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Risk_Gaussian_Mean": 8,
    "Risk_Gaussian_Std_Dev": 1.5
}

Risk_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the biting risk when Risk_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Risk_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Risk_Gaussian_Mean": 8,
    "Risk_Gaussian_Std_Dev": 1.5
}

Risk_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the biting risk when Risk_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Risk_Distribution": "WEIBULL_DISTRIBUTION",
    "Risk_Kappa": 0.9,
    "Risk_Lambda": 1.5
}

Risk_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the biting risk when Risk_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Risk_Distribution": "WEIBULL_DISTRIBUTION",
    "Risk_Kappa": 0.9,
    "Risk_Lambda": 1.5
}

Risk_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the biting risk when Risk_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Risk_Log_Normal_Mu": 9,
    "Risk_Log_Normal_Sigma": 2
}

Risk_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The width of the biting risk when Risk_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Risk_Log_Normal_Mu": 9,
    "Risk_Log_Normal_Sigma": 2
}

Risk_Max

float

0

3.40282E+38

-1

The maximum biting risk when Risk_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Risk_Distribution": "UNIFORM_DISTRIBUTION",
    "Risk_Min": 2,
    "Risk_Max": 7
}

Risk_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution when Risk_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Risk_Mean_1": 4,
    "Risk_Mean_2": 12,
    "Risk_Proportion_1": 0.2
}

Risk_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution when Risk_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Risk_Mean_1": 4,
    "Risk_Mean_2": 12,
    "Risk_Proportion_1": 0.2
}

Risk_Min

float

0

3.40282E+38

-1

The minimum biting risk when Risk_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Risk_Distribution": "UNIFORM_DISTRIBUTION",
    "Risk_Min": 2,
    "Risk_Max": 7
}

Risk_Peak_2_Value

float

0

3.40282E+38

-1

The biting risk value to assign to the remaining individuals when Risk_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Risk_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Risk_Proportion_0": 0.25,
    "Risk_Peak_2_Value": 5
}

Risk_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the biting risk when Risk_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Risk_Distribution": "POISSON_DISTRIBUTION",
    "Risk_Poisson_Mean": 5
}

Risk_Proportion_0

float

0

1

-1

The proportion of individuals to assign a value of zero biting risk when Risk_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Risk_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Risk_Proportion_0": 0.25,
    "Risk_Peak_2_Value": 5
}

Risk_Proportion_1

float

0

1

-1

The proportion of individuals in the first exponential distribution when Risk_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Risk_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Risk_Mean_1": 4,
    "Risk_Mean_2": 12,
    "Risk_Proportion_1": 0.2
}
OutbreakIndividualMalaria (malaria)

The OutbreakIndividualMalaria class extends OutbreakIndividual class and allows for specifying a specific strain of infection.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Clade

integer

0

9

0

The clade ID (Clade) of the outbreak infection. Together with the genome ID (Genome) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Clade may range from 0 to Number_of_Clades-1.

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "Outbreak"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Ignore_Immunity

boolean

0

1

1

Individuals will be force-infected (with a specific strain) regardless of actual immunity level when set to true (1).

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "class": "OutbreakIndividual",
        "Ignore_Immunity": 0
    }
}

Incubation_Period_Override

integer

-1

2147480000.0

-1

The incubation period, in days, that infected individuals will go through before becoming infectious. This value overrides the incubation period set in the configuration file. Set to -1 to honor the configuration parameter settings.

 
{
    "Incubation_Period_Override": 0
}

The following campaign class is new for the TBHIV model:

TBHIVConfigurableTBdrug (tuberculosis)

The TBHIVConfigurableTBdrug class is an individual level intervention for TB treatment. The intervention applies TB drug effects to the progression, associated mortality, transmission and acquisition of TB infections in HIV positive and negative individuals.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Active_Multiplier

array of floats

0

1

1

Multiplier of clearance/inactivation if active TB on drug treatment. Relapse, mortality, and resistance apply only to active.

 
{
    "Active_Multiplier": 1
}

Cost_To_Consumer

float

0

99999

1

The unit cost per drug (unamortized).

 
{
    "Cost_To_Consumer": 10
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Dose_Interval

float

0

99999

1

The interval between doses, in days.

 
{
    "Dose_Interval": 1
}

Drug_Cmax

float

0

10000

1

The maximum drug concentration that can be used, and is in the same units as Drug_PKPD_C50. Since drug concentrations and C50 values are often specified with different unit systems, these two parameters have been designed to be flexible provided that the units are the same for each. This parameter is used when Durability_Profile is set to CONCENTRATION_VERSUS_TIME.

 
{
    "Durability_Profile": "CONCENTRATION_VERSUS_TIME",
    "Drug_Cmax": 200,
    "Drug_PKPD_C50": 6,
    "Drug_Vd": 1
}

Drug_PKPD_C50

float

0

10000

1

The concentration at which drug killing rates are half of the maximum. Must use the same units as Drug_Cmax. This parameter is used when Durability_Profile is set to CONCENTRATION_VERSUS_TIME.

 
{
    "Durability_Profile": "CONCENTRATION_VERSUS_TIME",
    "Drug_Cmax": 200,
    "Drug_PKPD_C50": 6,
    "Drug_Vd": 1
}

Drug_Vd

float

0

10000

1

The volume of drug distribution. This value is the ratio of the volume of the second compartment to the volume of the first compartment in a two-compartment model, and is dimensionless. This parameter is used when Durability_Profile is set to CONCENTRATION_VERSUS_TIME.

 
{
    "Durability_Profile": "CONCENTRATION_VERSUS_TIME",
    "Drug_Cmax": 200,
    "Drug_PKPD_C50": 6,
    "Drug_Vd": 1
}

Durability_Profile

enum

NA

NA

FIXED_DURATION_CONSTANT_EFFECT

The profile of durability decay. Possible values are:

FIXED_DURATION_CONSTANT_EFFECT

The durability does not decay.

CONCENTRATION_VERSUS_TIME

Conditionally loads the following parameters: Drug_Cmax, Drug_PKPD_C50, and Drug_Vd.

 
{
    "Durability_Profile": "CONCENTRATION_VERSUS_TIME",
    "Drug_Cmax": 200,
    "Drug_PKPD_C50": 6,
    "Drug_Vd": 1
}

Fraction_Defaulters

float

0

1

0

The fraction of individuals who will not finish their drug treatment.

 
{
    "Fraction_Defaulters": 0
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "TBHIVConfigurableTBdrug",
        "Intervention_Name": "Isoniazid distribution"
    }
}

Latency_Multiplier

array of floats

0

1

1

Multiplier of clearance/inactivation if latent TB on drug treatment for the TB drug cure rate parameters (TB_Drug_Cure_Rate, TB_Drug_Cure_Rate_MDR, TB_Drug_Cure_Rate_HIV ) and the TB drug inactivation rate parameters (TB_Drug_Inactivation_Rate, TB_Drug_Inactivation_Rate_MDR, TB_Drug_Inactivation_Rate_HIV).

 
{
    "Latency_Multiplier": 1
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Primary_Decay_Time_Constant

float

0

1.00E+00

0

The primary decay time constant (in days) of the decay profile.

 
{
    "Primary_Decay_Time_Constant": 180
}

Remaining_Doses

integer

0

999999

0

The remaining doses in an intervention; enter a negative number for unlimited doses.

 
{
    "Remaining_Doses": 1
}

Secondary_Decay_Time_Constant

float

0

999999

1

The secondary decay time constant of the durability profile. This parameter is used when Durability_Profile is set to CONCENTRATION_VERSUS_TIME.

 
{
    "Durability_Profile": "CONCENTRATION_VERSUS_TIME",
    "Secondary_Decay_Time_Constant": 730
}

TB_Drug_Name

string

NA

NA

NA

The name of TB drug used in the TBHIVConfigurationTBdrug intervention. This must be one of the listed drugs as specificed under TBHIV_Drug_Types in the configuration file.

 
{
    "Active_Multiplier": 1,
    "Durability_Profile": "FIXED_DURATION_CONSTANT_EFFECT",
    "Latency_Multiplier": 1,
    "Remaining_Doses": 1,
    "TB_Drug_Name": "PreDOTSLowNoMDR",
    "class": "TBHIVConfigurableTBdrug"
}

TB_Reduced_Acquire

array of floats

0

1

0

Proportion reduction in acquisition of new TB infection under drug treatment. Only relevant when TB_Enable_Exogenous is enabled to allow exogenous re-infection.

 
{
    "TBHIV_Drug_Params": {
        "ACFDOTS": {
            "TB_Drug_Cure_Rate": 0.25,
            "TB_Drug_Inactivation_Rate": 1e-09,
            "TB_Drug_Inactivation_Rate_HIV": 1e-09,
            "TB_Drug_Inactivation_Rate_MDR": 1e-09,
            "TB_Drug_Mortality_Rate": 1e-09,
            "TB_Drug_Mortality_Rate_HIV": 1e-09,
            "TB_Drug_Mortality_Rate_MDR": 1e-09,
            "TB_Drug_Primary_Decay_Time_Constant": 179,
            "TB_Drug_Relapse_Rate": 1e-09,
            "TB_Drug_Relapse_Rate_HIV": 1e-09,
            "TB_Drug_Relapse_Rate_MDR": 1e-09,
            "TB_Drug_Resistance_Rate": 1e-09,
            "TB_Drug_Resistance_Rate_HIV": 1e-09,
            "TB_Reduced_Acquire": 1,
            "TB_Reduced_Transmit": 1,
            "TB_Drug_Cure_Rate_HIV": 0,
            "TB_Drug_Cure_Rate_MDR": 0
        }
    }
}

TB_Reduced_Transmit

array of floats

0

1

0

Proportion reduction in TB transmission under drug treatment. The value scales the Base_Infectivity parameter.

 
{
    "TBHIV_Drug_Params": {
        "ACFDOTS": {
            "TB_Drug_Cure_Rate": 0.25,
            "TB_Drug_Inactivation_Rate": 1e-09,
            "TB_Drug_Inactivation_Rate_HIV": 1e-09,
            "TB_Drug_Inactivation_Rate_MDR": 1e-09,
            "TB_Drug_Mortality_Rate": 1e-09,
            "TB_Drug_Mortality_Rate_HIV": 1e-09,
            "TB_Drug_Mortality_Rate_MDR": 1e-09,
            "TB_Drug_Primary_Decay_Time_Constant": 179,
            "TB_Drug_Relapse_Rate": 1e-09,
            "TB_Drug_Relapse_Rate_HIV": 1e-09,
            "TB_Drug_Relapse_Rate_MDR": 1e-09,
            "TB_Drug_Resistance_Rate": 1e-09,
            "TB_Drug_Resistance_Rate_HIV": 1e-09,
            "TB_Reduced_Acquire": 1,
            "TB_Reduced_Transmit": 1,
            "TB_Drug_Cure_Rate_HIV": 0,
            "TB_Drug_Cure_Rate_MDR": 0
        }
    }
}
Deprecated demographics parameters

ImmunityDistributionFlag, ImmunityDistribution1, and ImmunityDistribution2 were renamed to SusceptibilityDistributionFlag, SusceptibilityDistribution1, and SusceptibilityDistribution2. In previous versions of EMOD, the naming was counterintuitive to the functionality. For example, setting a value of 1 for the immunity indicated zero immunity/complete susceptibility. Now the parameters more accurately reflect that you are setting a susceptibility value. The functionality is the same.

Deprecated config parameters

Immunity_Transmission_Factor, Immunity_Mortality_Factor, and Immunity_Acquisition_Factor were renamed to Post_Infection_Transmission_Multiplier, Post_Infection_Mortality_Multiplier, and Post_Infection_Acquistion_Multiplier. The functionality is the same.

Deprecated campaign parameters

The TB_SIM simulation type has been deprecated and replaced with TBHIV_SIM, which does not include HIV transmission but adds the ability to model the effect of HIV coinfection on the spread of TB.

The following campaign classes, which have not yet been fully tested with the TBHIV simulation type, have been disabled:

  • HealthSeekingBehaviorUpdate

  • HealthSeekingBehaviorUpdateable

  • AntiTBPropDepDrug

  • SmearDiagnostic

In previous versions of EMOD, you could set the tendency of individuals to seek out health care using HealthSeekingBehaviorUpdateable and then update the value of the Tendency parameter using HealthSeekingBehaviorUpdate. Now, you use individual properties to update individuals when they receive the SimpleHealthSeekingBehavior intervention, as you would to control the flow of individuals through other intervention classes. For example, you could create an individual property with HSBold and HSBnew values in the demographics file and assign all individuals to HSBold. Then you could distribute the first SimpleHealthSeekingBehavior (with one Tendency value) to all HSBold individuals and use New_Property_Value to assign them to HSBnew after receiving the intervention. The next SimpleHealthSeekingBehavior intervention (with a different Tendency value) could be distributed, setting Disqualifying_Properties to HSBold and, if desired, using New_Property_Value to reassign HSBold to those individuals.

Similarly, AntiTBPropDepDrug was disabled and superseded with TBHIVConfigurableTBDrug, which allows for drug effects based on HIV status and where dependence on IndividualProperties is configured through Property_Restrictions. In addition, AntiTBPropDepDrub can be replaced with AntiTBDrug, also using Property_Restrictions and new property values to target particular individuals with drug interventions for tuberculosis without HIV coinfections.

SmearDiagnostic was disabled and can be replaced with DiagnosticTreatNeg. While SmearDiagnostic would only broadcast when an individual had a positive smear diagnostic, DiagnosticTreatNeg has the added benefit of broadcasting negative and default diagnostic test events.

TB_Drug_Clearance_Rate_HIV and TB_Drug_Clearance_Rate_MDR parameters have been renamed to TB_Drug_Cure_Rate_HIV and TB_Drug_Cure_Rate_MDR.

Error messages

When attempting to run an intervention using one of the disabled tuberculosis classes, such as AntiTBPropDepDrug, HealthSeekingBehaviorUpdate, HealthSeekingBehaviorUpdateable, and SmearDiagnostic, you will receive an error similar to the following: “00:00:01 [0] [I] [JsonConfigurable] Using the default value ( “Intervention_Name” : “HealthSeekingBehaviorUpdateable” ) for unspecified parameter. 00:00:02 [0] [E] [Eradication] 00:00:02 [0] [E] [Eradication] GeneralConfigurationException: Exception in SimulationEventContext.cpp at 242 in Kernel::SimulationEventContextHost::LoadCampaignFromFile. Array out of bounds”

Note

These campaign classes have been disabled because they have not yet been fully tested with the TBHIV simulation type.

EMOD schema and simulation types

In the schema for the Simulation_Type parameter the enum values list additional simulation types that are not supported by EMOD.

EMOD supports the following simulation types for modeling a variety of diseases:

  • Generic disease (GENERIC_SIM), which can be used for modeling a variety of diseases such as influenza or measles

  • Vector-borne diseases (VECTOR_SIM), which can be used for modeling vector-borne diseases such as dengue

  • Malaria (MALARIA_SIM), which adds features specific to malaria biology and treatment

  • Tuberculosis with HIV coinfection (TBHIV_SIM), which can be used for modeling TB transmission, with the option to add HIV coinfection as a contributing factor

  • Sexually transmitted infections (STI_SIM), which adds features for sexual relationship networks

  • HIV (HIV_SIM), which adds features specific to HIV biology and treatment

  • Environmental transmission (ENVIRONMENTAL_SIM), which adds features for diseases transmitted through contaminated food or water

  • Typhoid (TYPHOID_SIM), which adds features specific to typhoid biology and treatment

For information about building the schema, see Generate a list of all available parameters (a schema).

EMOD v2.13

The EMOD v2.13 release includes many new features for all supported simulation types.

New configuration parameters

For the HIV simulation type, the following new configuration parameters are available:

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Custom_Reports_Filename

string

NA

NA

UNINITIALIZED STRING

The name of the file containing custom report configuration parameters. Omitting this parameter or setting it to RunAllCustomReports will load all reporters found that are valid for the given simulation type. The file must be in JSON format.

 
{  
    "Custom_Reports_Filename": "custom_reports.json"
}

Heterogeneous_Infectiousness_LogNormal_Scale

float

0

10

0

Scale parameter of a log normal distribution that governs an infectiousness multiplier. The multiplier represents heterogeneity in infectivity and adjusts Base_Infectivity.

 
{
    "Heterogeneous_Infectiousness_LogNormal_Scale": 1
}

Incubation_Period_Log_Mean

float

0

3.40E+38

6

The mean of log normal for the incubation period distribution. Incubation_Period_Distribution must be set to LOG_NORMAL_DURATION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DURATION",
    "Incubation_Period_Log_Mean": 5.758,
    "Incubation_Period_Log_Width": 0.27
}

Incubation_Period_Log_Width

float

0

3.40E+38

1

The log width of log normal for the incubation period distribution. Incubation_Period_Distribution must be set to LOG_NORMAL_DURATION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DURATION",
    "Incubation_Period_Log_Mean": 5.758,
    "Incubation_Period_Log_Width": 0.27
}

Infectivity_Exponential_Baseline

float

0

1

0

The scale factor applied to Base_Infectivity at the beginning of a simulation, before the infectivity begins to grow exponentially. Infectivity_Scale_Type must be set to EXPONENTIAL_FUNCTION_OF_TIME.

 
{
    "Infectivity_Exponential_Baseline": 0.1, 
    "Infectivity_Exponential_Delay": 90, 
    "Infectivity_Exponential_Rate": 45, 
    "Infectivity_Scale_Type": "EXPONENTIAL_FUNCTION_OF_TIME"
}

Infectivity_Exponential_Delay

float

0

3.40E+38

0

The number of days before infectivity begins to ramp up exponentially. Infectivity_Scale_Type must be set to EXPONENTIAL_FUNCTION_OF_TIME.

 
{
    "Infectivity_Exponential_Baseline": 0.1, 
    "Infectivity_Exponential_Delay": 90, 
    "Infectivity_Exponential_Rate": 45, 
    "Infectivity_Scale_Type": "EXPONENTIAL_FUNCTION_OF_TIME"
}

Infectivity_Exponential_Rate

float

0

3.40E+38

0

The daily rate of exponential growth to approach to full infectivity after the delay set by Infectivity_Exponential_Delay has passed. Infectivity_Scale_Type must be set to EXPONENTIAL_FUNCTION_OF_TIME.

 
{
    "Infectivity_Exponential_Rate": 45
}

Memory_Usage_Halting_Threshold_Working_Set_MB

integer

0

1.00E+06

8000

The maximum size (in MB) of working set memory before the system throws an exception and halts.

 
{
    "Memory_Usage_Halting_Threshold_Working_Set_MB": 4000
}

Memory_Usage_Warning_Threshold_Working_Set_MB

integer

0

1.00E+06

7000

The maximum size (in MB) of working set memory before memory usage statistics are written to the log regardless of log level.

 
{
    "Memory_Usage_Warning_Threshold_Working_Set_MB": 3500
}

Report_HIV_ByAgeAndGender_Add_Relationships

boolean

0

1

0

Sets whether or not the ReportHIVByAgeAndGender.csv output file will contain data by relationship type on population currently in a relationship and ever in a relationship. A sum of those in two or more partnerships and a sum of the lifetime number of relationships in each bin will be included.

 
{
    "Report_HIV_ByAgeAndGender_Add_Relationships": 1
}

Report_HIV_ByAgeAndGender_Add_Transmitters

boolean

0

1

0

When Set to to true (1), the “transmitters” column is included in the output report. For a given row, “Transmitters” indicates how many people that have transmitted the disease meet the specifications of that row.

 
{
    "Report_HIV_ByAgeAndGender_Add_Transmitters": 1
}

Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data

array of floats

-3.40282e+38

3.40282e+38

1

This array of floats allows the user to define the age bins used to stratify the report by age. Each value defines the minimum value of that bin, while the next value defines the maximum value of the bin. The maximum number of age bins is 100. For example, if you had:

“Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data” : [ 0, 10, 20, 50, 100 ]

The report would have the following age bins: From 0 up to (but not including) 10, from 10 up to (but not including) 20, from 20 up to (but not including) 50, from 50 up to (but not including) 100, and 100 and over.

If no values are specified in the array, then the output report will have no age binning.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data" : [
        0,  1,  2,  3,  4,  5,  6,  7,  8,  9,
        10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
        20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
        30, 31, 32, 33, 34, 35, 36, 37, 38, 39,
        40, 41, 42, 43, 44, 45, 46, 47, 48, 49,
        50, 51, 52, 53, 54, 55, 56, 57, 58, 59,
        60, 61, 62, 63, 64, 65, 66, 67, 68, 69,
        70, 71, 72, 73, 74, 75, 76, 77, 78, 79,
        80, 81, 82, 83, 84, 85, 86, 87, 88, 89,
        90, 91, 92, 93, 94, 95, 96, 97, 98, 99
    ]
}

Report_HIV_ByAgeAndGender_Collect_Gender_Data

boolean

0

1

0

Controls whether or not the report is stratified by gender; to enable gender stratification, set to true (1).

 
{
    "Report_HIV_ByAgeAndGender_Collect_Gender_Data": 1
}

Report_HIV_ByAgeAndGender_Collect_Intervention_Data

array of strings

NA

NA

NA

Stratifies the population by adding a column of 0s and 1s depending on whether or not the person has the indicated intervention. This only works for interventions that remain with a person for a period of time, such as ART, VMMC, vaccine/PrEP, or a delay state in the cascade of care. You can name the intervention by adding a parameter Intervention_Name in the campaign file, and then give this parameter the same Intervention_Name. This allows you to have multiple types of vaccines, VMMCs, etc., but to only stratify on the type you want.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Intervention_Data": [
        "ART_Intervention",
        "PrEP_Intervention" 
    ]
}

Serialization_Time_Steps

array of integers

0

2.15E+09

The list of time steps after which to save the serialized state. 0 (zero) indicates the initial state before simulation, n indicates after the nth time step. By default, no serialized state is saved.

 
{
    "Serialization_Time_Steps": [
        0, 
        10
    ]
}

Serialized_Population_Filenames

array of strings

NA

NA

NA

Array of filenames with serialized population data. The number of filenames must match the number of cores used for the simulation. The file must be in .dtk format.

 
{
    "Serialized_Population_Filenames": [
        "state-00010.dtk"
    ]
}

Serialized_Population_Path

string

NA

NA

.

The root path for the serialized population files.

 
{
    "Serialized_Population_Path": "../00_Generic_Version_1_save/output"
}

To view all available configuration parameters, see Configuration parameters.

New demographics parameters

In all simulation types, you can now assign properties like risk or quality of care to nodes using NodeProperties, which are configured much like IndividualProperties. In addition, a new property type is available for both nodes and individuals called InterventionStatus, which is used by the campaign file to distribute interventions based on the other interventions an individual or node has received. This property type was previously available only for individuals in the HIV simulation type and was known as the CascadeState. The relevant campaign parameters are described in the next section.

For more information, see the table below.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

NodeProperties

array of objects

NA

NA

NA

An array that contains parameters that add properties to nodes in a simulation. For example, you can define values for intervention status, risk, and other properties and assign values to different nodes.

 
{
    "NodeProperties": [{
        "Property": "Risk",
        "Values": ["HIGH", "MEDIUM", "LOW"],
        "Initial_Distribution": [0.1, 0.4, 0.5]
    }]
}

Property

enum

NA

NA

NA

The individual or node property type for which you will assign arbitrary values to create groups. You can then move individuals or nodes into or out of different groups or target interventions to particular groups. Possible values are:

Age_Bin

Assign individuals to age bins. Use with Age_Bin_Edges_In_Years. Cannot be used with NodeProperties.

Accessibility

Tag individuals or nodes based on their accessibility.

Geographic

Tag individuals or nodes based on geographic characteristics.

HasActiveTB

Tag individuals or nodes based on active TB status. Typically used only with HIV ART staging interventions.

InterventionStatus

Tag individuals or nodes based on intervention status, so that receiving an intervention can affect how other interventions are distributed. Use with Disqualifying_Properties and New_Property_Value in the campaign file.

Place

Tag individuals or nodes based on place.

Risk

Tag individuals or nodes based on disease risk.

QualityofCare

Tag individuals or nodes based on the quality of medical care.

 
{
    "Defaults": {
        "IndividualProperties": [{
            "Property": "Age_Bin",
            "Age_Bin_Edges_In_Years": [ 0, 6, 10, 20, -1 ]
        }]
    }
}

{
    "NodeProperties": [{
        "Property": "InterventionStatus",
        "Values": ["NONE", "RECENT_SPRAY"],
        "Initial_Distribution": [1.0, 0.0]
    }]
}
New campaign parameters

The addition of NodeProperties in the demographics file also necessitated the addition of Node_Property_Restrictions to control how interventions are distributed based on the property values assigned to each node.

The new campaign parameters Disqualifying_Properties and New_Property_Value were added to every intervention to control how interventions are distributed based on properties assigned to individuals or nodes. Disqualifying_Properties prevents an intervention from being distributed to individuals or nodes with certain property values. New_Property_Value updates the property value after they receive an intervention.

These are generally used with the the property type InterventionStatus to control how interventions are distributed based on the interventions already received. For example, a household may be ineligible for clinical treatment for a length of time if they already received treatment during a drug campaign. This functionality was previously only available for individuals in the HIV simulation type and used parameters previously called Abort_States and Valid_Cascade_States.

The following event coordinators and intervention classes are new for this simulation type.

CommunityHealthWorkerEventCoordinator

The CommunityHealthWorkerEventCoordinator coordinator class is used to model a health care worker’s ability to distribute interventions to the nodes and individual in their coverage area. This coordinator distributes a limited number of interventions per day, and can create a backlog of individuals or nodes requiring the intervention. For example, individual-level interventions could be distribution of drugs and node-level interventions could be spraying houses with insecticide.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Amount_In_Shipment

integer

1

2147480000.0

2147480000.0

The number of interventions (such as vaccine doses) that a health worker or clinic receives in a shipment. Interventions can only be distributed if they are in stock; stock is updated every Days_Between_Shipments with the Amount_In_Shipment.

 
{
    "Amount_In_Shipment": 10
}

Days_Between_Shipments

float

1

3.40282e+38

3.40E+38

The number of days to wait before a clinic or health worker receives a new shipment of interventions (such as vaccine doses). Interventions can only be distributed if they are in stock; stock is updated every Days_Between_Shipments with the Amount_In_Shipment.

 
{
    "Days_Between_Shipments": 30
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Duration

float

0

3.40282e+38

3.40E+38

The number of days for an event coordinator to be active before it expires.

 
{
    "Duration": 65
}

Initial_Amount_Constant

float

0

3.40282E+38

-1

The initial amount to use for all health workers when Initial_Amount_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "CONSTANT_DISTRIBUTION",
    "Initial_Amount_Constant": 8
}

Initial_Amount_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the initial amount of interventions in stock. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Initial_Amount_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Initial_Amount_Max and Initial_Amount_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Initial_Amount_Gaussian_Mean and Initial_Amount_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Initial_Amount_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Initial_Amount_Kappa and Initial_Amount_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Initial_Amount_Log_Normal_Mu and Initial_Amount_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Initial_Amount_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Initial_Amount_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Initial_Amount_Mean_1, Initial_Amount_Mean_2, and Initial_Amount_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Exponential

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Exponential": 4.25
}

Initial_Amount_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Initial_Amount_Gaussian_Mean": 8,
    "Initial_Amount_Gaussian_Std_Dev": 1.5
}

Initial_Amount_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the initial amount of intervention in stock when Initial_Amount_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Initial_Amount_Gaussian_Mean": 8,
    "Initial_Amount_Gaussian_Std_Dev": 1.5
}

Initial_Amount_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the initial amount of intervention in stock when Initial_Amount_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "WEIBULL_DISTRIBUTION",
    "Initial_Amount_Kappa": 0.9,
    "Initial_Amount_Lambda": 1.5
}

Initial_Amount_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the initial amount of intervention in stock when Initial_Amount_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "WEIBULL_DISTRIBUTION",
    "Initial_Amount_Kappa": 0.9,
    "Initial_Amount_Lambda": 1.5
}

Initial_Amount_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the initial amount of intervention in stock when Initial_Amount_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Initial_Amount_Log_Normal_Mu": 9,
    "Initial_Amount_Log_Normal_Sigma": 2
}

Initial_Amount_Log_Normal_Sigma

float

-3.40282e+38

3.40282E+38

1

The standard deviation of the natural log of the initial amount of intervention in stock when Initial_Amount_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Initial_Amount_Log_Normal_Mu": 9,
    "Initial_Amount_Log_Normal_Sigma": 2
}

Initial_Amount_Max

float

0

3.40282E+38

-1

The maximum initial amount of intervention in stock when Initial_Amount_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "UNIFORM_DISTRIBUTION",
    "Initial_Amount_Min": 2,
    "Initial_Amount_Max": 7
}

Initial_Amount_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Min

float

0

3.40282E+38

-1

The minimum of initial amount of intervention in stock when Initial_Amount_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "UNIFORM_DISTRIBUTION",
    "Initial_Amount_Min": 2,
    "Initial_Amount_Max": 7
}

Initial_Amount_Peak_2_Value

float

0

3.40282E+38

-1

The initial amount in stock to assign to the remaining health workers when Initial_Amount_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Initial_Amount_Proportion_0": 0.25,
    "Initial_Amount_Peak_2_Value": 5
}

Initial_Amount_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to the POISSON_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "POISSON_DISTRIBUTION",
    "Initial_Amount_Poisson_Mean": 5
}

Initial_Amount_Proportion_0

float

0

1

-1

The proportion of health workers to assign a value of zero stock when Initial_Amount_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Initial_Amount_Proportion_0": 0.25,
    "Initial_Amount_Peak_2_Value": 5
}

Initial_Amount_Proportion_1

float

0

1

-1

The proportion of health workers in the first exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "BroadcastEvent",
        "Broadcast_Event": "EventFromIntervention"
    }
}

Max_Distributed_Per_Day

integer

1

2147480000.0

2147480000.0

The maximum number of interventions (such as vaccine doses) that can be distributed by health workers or clinics in a given day.

 
{
    "Max_Distributed_Per_Day": 1
}

Max_Stock

integer

0

2147480000.0

2147480000.0

The maximum number of interventions (such as vaccine doses) that can be stored by a health worker or clinic. If the amount of interventions in a new shipment and current stock exceeds this value, only the number of interventions specified by this value will be stored.

 
{
    "Max_Stock": 12
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Trigger_Condition_List

array of strings

NA

NA

NA

The list of events that are of interest to the community health worker (CHW). If one of these events occurs, the individual or node is put into a queue to receive the CHW’s intervention. The CHW processes the queue when the event coordinator is updated. See Event list for possible values.

 
{
    "Trigger_Condition_List": [
        "ListenForEvent"
    ]
}

Waiting_Period

float

0

3.40282e+38

3.40E+38

The number of days a person or node can be in the queue waiting to get the intervention from the community health worker (CHW). If a person or node is in the queue, they will not be re-added to the queue if the event that would add them to the queue occurs. This allows them to maintain their priority, however they could be removed from the queue due to this waiting period.

 
{
    "Waiting_Period": 15
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}
ImportPressure

The ImportPressure intervention class extends the ImportCases outbreak event. Rather than importing a deterministic number of cases on a scheduled day, ImportPressure applies a set of per-day rates of importation of infected individuals, over a corresponding set of durations. ImportPressure inherits from Outbreak; the Antigen and Genome parameters are defined as they are for all Outbreak events.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Daily_Import_Pressures

array of floats

0

3.40282e+38

0

The rate of per-day importation for each node that the intervention is distributed to.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Durations": [
            100,
            100,
            100,
            100,
            100,
            100,
            100
        ],
        "Daily_Import_Pressures": [
            0.1,
            5.0,
            0.2,
            1.0,
            2.0,
            0.0,
            10.0
        ],
        "class": "ImportPressure"
    }
}

Durations

array of integers

0

2147480000.0

1

The durations over which to apply import pressure.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Durations": [
            100,
            100,
            100,
            100,
            100,
            100,
            100
        ],
        "Daily_Import_Pressures": [
            0.1,
            5.0,
            0.2,
            1.0,
            2.0,
            0.0,
            10.0
        ],
        "class": "ImportPressure"
    }
}

Genome

integer

0

16777215

0

The genome ID (Genome) of the outbreak infection. Together with the clade ID (Clade) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Genome may range from -1 to 2Log2_Number_of_Genomes_per_Clade-1

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "OutbreakIndividual"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "OutbreakIndividual",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Import_Age

float

0

43800

365

The age (in days) of infected import cases.

 
{
    "Import_Age": 10000
}

Incubation_Period_Override

integer

-1

2147480000.0

-1

The incubation period, in days, that infected individuals will go through before becoming infectious. This value overrides the incubation period set in the configuration file. Set to -1 to honor the configuration parameter settings.

 
{
    "Incubation_Period_Override": 0
}

Number_Cases_Per_Node

integer

0

2147480000.0

1

The number of new cases of Outbreak to import (per node).

Note

This will increase the population and there is no control over demographics of these individuals.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "ImportCases",
        "Number_Cases_Per_Node": 10,
        "class": "Outbreak"
    }
}
IndividualImmunityChanger

The IndividualImmunityChanger intervention class acts essentially as a MultiEffectVaccine, with the exception of how the behavior is implemented. Rather than attaching a persistent vaccine intervention object to an individual’s intervention list (as a campaign-individual-multieffectboostervaccine does), the IndividualImmunityChanger directly alters the immune modifiers of the individual’s susceptibility object and is then immediately disposed of. Any immune waning is not governed by Waning effect classes, as MultiEffectVaccine is, but rather by the immunity waning parameters in the configuration file.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Boost_Acquire

float

0

1

0

Specifies the boosting effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Acquire": 0.7
}

Boost_Mortality

float

0

1

0

Specifies the boosting effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Mortality": 1.0
}

Boost_Threshold_Acquire

float

0

1

0

Specifies how much acquisition immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Acquire": 0.0
}

Boost_Threshold_Mortality

float

0

1

0

Specifies how much mortality immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Mortality": 0.0
}

Boost_Threshold_Transmit

float

0

1

0

Specifies how much transmission immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Transmit": 0.0
}

Boost_Transmit

float

0

1

0

Specifies the boosting effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Transmit": 0.5
}

Cost_To_Consumer

float

0

999999

1

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Prime_Acquire

float

0

1

0

Specifies the priming effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Acquire": 0.1
}

Prime_Mortality

float

0

1

0

Specifies the priming effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Mortality": 0.3
}

Prime_Transmit

float

0

1

0

Specifies the priming effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Transmit": 0.2
}
MultiEffectBoosterVaccine

The MultiEffectBoosterVaccine intervention class is derived from MultiEffectVaccine and preserves many of the same parameters. Upon distribution and successful take, the vaccine’s effect in each immunity compartment (acquisition, transmission, and mortality) is determined by the recipient’s immune state. If the recipient’s immunity modifier in the corresponding compartment is above a user-specified threshold, then the vaccine’s initial effect will be equal to the corresponding priming parameter. If the recipient’s immune modifier is below this threshold, then the vaccine’s initial effect will be equal to the corresponding boost parameter. After distribution, the effect wanes, just like a MultiEffectVaccine. The behavior is intended to mimic biological priming and boosting.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acquire_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine acquisition. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Acquire_Config": {
        "Initial_Effect": 0.9,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Boost_Acquire

float

0

1

0

Specifies the boosting effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Acquire": 0.7
}

Boost_Mortality

float

0

1

0

Specifies the boosting effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Mortality": 1.0
}

Boost_Threshold_Acquire

float

0

1

0

Specifies how much acquisition immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Acquire": 0.0
}

Boost_Threshold_Mortality

float

0

1

0

Specifies how much mortality immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Mortality": 0.0
}

Boost_Threshold_Transmit

float

0

1

0

Specifies how much transmission immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Transmit": 0.0
}

Boost_Transmit

float

0

1

0

Specifies the boosting effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Transmit": 0.5
}

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

MultiEffectBoosterVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiEffectBoosterVaccine",
        "Intervention_Name": "Tetanus booster shot"
    }
}

Mortality_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine mortality. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Mortality_Config": {
        "Initial_Effect": 1.0,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prime_Acquire

float

0

1

0

Specifies the priming effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Acquire": 0.1
}

Prime_Mortality

float

0

1

0

Specifies the priming effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Mortality": 0.3
}

Prime_Transmit

float

0

1

0

Specifies the priming effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Transmit": 0.2
}

Transmit_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine transmission. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Transmit_Config": {
        "Initial_Effect": 0.6,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}
NodePropertyValueChanger

The NodePropertyValueChanger intervention class sets a given node property to a new value. You can also define a duration in days before the node property reverts back to its original value, the probability that a node will change its node property to the target value, and the number of days over which nodes will attempt to change their individual properties to the target value. This node-level intervention functions in a similar manner as the individual-level intervention, PropertyValueChanger.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Daily_Probability

float

0

1

1

The daily probability that the node’s property value changes to the Target_NP_Key_Value.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

NodePropertyValueChanger

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Name": "Diagnostic_Sample"
}

Maximum_Duration

float

-1

3.40E+38

3.40E+38

The maximum amount of time in days nodes have to update the property value. This timing works in conjunction with Daily_Probability.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Revert

float

0

10000

0

The number of days before the node’s property value reverts back to the initial node property value.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Target_NP_Key_Value

string

NA

NA

NA

The NodeProperty key:value pair, as defined in the demographics file, to assign to the node.

 
{
    "Target_NP_Key_Value": "InterventionStatus:NONE"
}
SimpleBoosterVaccine

The SimpleBoosterVaccine intervention class is derived from SimpleVaccine and preserves many of the same parameters. The behavior is much like SimpleVaccine, except that upon distribution and successful take, the vaccine’s effect is determined by the recipient’s immune state. If the recipient’s immunity modifier in the corresponding channel (acquisition, transmission, or mortality) is above a user-specified threshold, then the vaccine’s initial effect will be equal to the corresponding priming parameter. If the recipient’s immune modifier is below this threshold, then the vaccine’s initial effect will be equal to the corresponding boosting parameter. After distribution, the effect wanes, just like SimpleVaccine. In essence, this intervention provides a SimpleVaccine intervention with one effect to all naive (below- threshold) individuals, and another effect to all primed (above-threshold) individuals; this behavior is intended to mimic biological priming and boosting.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Boost_Effect

float

0

1

1

Specifies the boosting effect on [acquisition/transmission/mortality] immunity for previously exposed individuals (either natural or vaccine-derived). This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Boost_Threshold

float

0

1

0

Specifies how much immunity is required before the vaccine changes from a priming effect to a boosting effect.

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Efficacy_Is_Multiplicative

boolean

NA

NA

1

The overall vaccine efficacy when individuals receive more than one vaccine. When set to true (1), the vaccine efficacies are multiplied together; when set to false (0), the efficacies are additive.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Intervention_Name

string

NA

NA

SimpleBoosterVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "SimpleBoosterVaccine",
        "Intervention_Name": "Tetanus booster shot"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prime_Effect

float

0

1

1

Specifies the priming effect on [acquisition/transmission/mortality] immunity for naive individuals (without natural or vaccine-derived immunity).

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Vaccine_Type

enum

NA

NA

Generic

The type of vaccine to distribute in a vaccine intervention. Possible values are:

Generic

The vaccine can reduce transmission, acquisition, and mortality.

TransmissionBlocking

The vaccine will reduce pathogen transmission.

AcquisitionBlocking

The vaccine will reduce the acquisition of the pathogen by reducing the force of infection experienced by the vaccinated individual.

MortalityBlocking

The vaccine reduces the disease-mortality rate of a vaccinated individual.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Waning_Config

JSON object

NA

NA

NA

The configuration of how the intervention efficacy wanes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Waning_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 1,
        "class": "WaningEffectBox"
    }
}
UsageDependentBednet (malaria)

The UsageDependentBednet intervention class is similar to SimpleBednet, as it distributes insecticide-treated nets to individuals in the simulation. However, bednet ownership and bednet usage are distinct in this intervention. As in SimpleBednet, net ownership is configured through the demographic coverage, and the blocking and killing rates of mosquitoes are time-dependent. Use of bednets is age-dependent and can vary seasonally. Once a net has been distributed to someone, the net usage is determined by the product of the seasonal and age-dependent usage probabilities until the net-retention counter runs out, and the net is discarded.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Blocking_Config

JSON object

NA

NA

NA

Configures the rate of blocking for indoor mosquito feeds on individuals with an ITN. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Blocking_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 0,
        "class": "WaningEffectBox"
    }
}

Cost_To_Consumer

float

0

999999

3.75

The unit cost per bednet (unamortized)

 
{
    "Cost_To_Consumer": 4.5
}

Discard_Event

enum

NA

NA

NA

The event that is broadcast when an individual discards their bed net, either by replacing an existing net or due to the expiration timer. See Event list for possible values, or you can use a custom event (defined in the Custom_Individudual_Events list in the config file).

 
{
    "Received_Event": "Bednet_Got_New_One",
    "Using_Event": "Bednet_Using",
    "Discard_Event": "Bednet_Discarded",
    "Expiration_Distribution_Type": "FIXED_DURATION",
    "Expiration_Period": 50
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Expiration_Period_Constant

float

0

3.40282E+38

-1

The expiration period to use for all bednets, in days, when Expiration_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Expiration_Period_Constant": 8
}

Expiration_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the expiration period to a usage-dependent bednet. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Expiration_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Expiration_Period_Max and Expiration_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Expiration_Period_Gaussian_Mean and Expiration_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Expiration_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Expiration_Period_Kappa and Expiration_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and width. Set Expiration_Period_Log_Normal_Mu and Expiration_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Expiration_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Expiration_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Expiration_Period_Mean_1, Expiration_Period_Mean_2, and Expiration_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_Before_Leaving_Log_Normal_Mu": 9,
    "Duration_Before_Leaving_Log_Normal_Sigma": 2
}

Expiration_Period_Exponential

float

0

3.40282E+38

-1

The mean of the expiration period, in days, when Expiration_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Expiration_Period_Exponential": 4.25
}

Expiration_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the expiration period, in days, when Expiration_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Expiration_Period_Gaussian_Mean": 8,
    "Expiration_Period_Gaussian_Std_Dev": 1.5
}

Expiration_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the expiration period, in days, when Expiration_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Expiration_Period_Gaussian_Mean": 8,
    "Expiration_Period_Gaussian_Std_Dev": 1.5
}

Expiration_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the expiration period, in days, when Expiration_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Expiration_Period_Kappa": 0.9,
    "Expiration_Period_Lambda": 1.5
}

Expiration_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the expiration period, in days, when Expiration_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Expiration_Period_Kappa": 0.9,
    "Expiration_Period_Lambda": 1.5
}

Expiration_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the expiration period, in days, when Expiration_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Expiration_Period_Log_Normal_Mu": 9,
    "Expiration_Period_Log_Normal_Sigma": 2
}

Expiration_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The width of the expiration period, in days, when Expiration_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Expiration_Period_Log_Normal_Mu": 9,
    "Expiration_Period_Log_Normal_Sigma": 2
}

Expiration_Period_Max

float

0

3.40282E+38

-1

The maximum expiration period, in days, when Expiration_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Expiration_Period_Min": 2,
    "Expiration_Period_Max": 7
}

Expiration_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Expiration_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Expiration_Period_Mean_1": 4,
    "Expiration_Period_Mean_2": 12,
    "Expiration_Period_Proportion_1": 0.2
}

Expiration_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Expiration_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Expiration_Period_Mean_1": 4,
    "Expiration_Period_Mean_2": 12,
    "Expiration_Period_Proportion_1": 0.2
}

Expiration_Period_Min

float

0

3.40282E+38

-1

The minimum expiration period, in days, when Expiration_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Expiration_Period_Min": 2,
    "Expiration_Period_Max": 7
}

Expiration_Period_Peak_2_Value

float

0

3.40282E+38

-1

The expiration period value to assign to the remaining bednets, in days, when Expiration_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Expiration_Period_Proportion_0": 0.25,
    "Expiration_Period_Peak_2_Value": 5
}

Expiration_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the expiration period, in days, when Expiration_Period is set to POISSON_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "POISSON_DISTRIBUTION",
    "Expiration_Period_Poisson_Mean": 5
}

Expiration_Period_Proportion_0

float

0

1

-1

The proportion of bednets to assign a value of zero days until expiration when Expiration_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Expiration_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Expiration_Period_Proportion_0": 0.25,
    "Expiration_Period_Peak_2_Value": 5
}

Expiration_Period_Proportion_1

float

0

1

-1

The proportion of bednets in the first exponential distribution.

 
{
    "Expiration_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Expiration_Period_Mean_1": 4,
    "Expiration_Period_Mean_2": 12,
    "Expiration_Period_Proportion_1": 0.2
}

Insecticide_Name

string

NA

NA

UNINITIALIZED STRING

The name of the insecticide defined in <config.Insecticides> for this intervention. If insecticides are being used, this must be defined as one of those values; if they are not being used this can be empty. It cannot have a value if you did not configure <config.Insecticides>.

 
{
    "Insecticide_Name": "carbamate"
}

Intervention_Name

string

NA

NA

UsageDependentBednet

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "UsageDependentBednet",
        "Intervention_Name": "IRS bednet that wears over time"
    }
}

Killing_Config

JSON object

NA

NA

NA

The configuration of the rate at which mosquitoes die, conditional on a successfully blocked feed. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Killing_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 0.53429,
        "class": "WaningEffectBox"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Received_Event

enum

NA

NA

NA

This parameter broadcasts when a new net is received, either the first net or a replacement net. See Event list for possible values, or you can use a custom event (defined in the Custom_Individudual_Events list in the config file).

 
{
    "Received_Event": "Bednet_Got_New_One",
    "Using_Event": "Bednet_Using",
    "Discard_Event": "Bednet_Discarded"
}

Repelling_Config

JSON object

NA

NA

NA

Defines a waning effect that determines the probability that a vector is repelled due to the intervention. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Repelling_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 0,
        "class": "WaningEffectBox"
    }
}

Usage_Config_List

array of JSON objects

NA

NA

NA

The list of WaningEffects whose effects are multiplied together to get the usage effect. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Usage_Config_List": [
        {
            "class": "WaningEffectConstant",
            "Initial_Effect": 1.0
        }
    ]
}

Using_Event

enum

NA

NA

NA

This parameter broadcasts each time step in which a bed net is used. See Event list for possible values, or you can use a custom event (defined in the Custom_Individudual_Events list in the config file).

 
{
    "Received_Event": "Bednet_Got_New_One",
    "Using_Event": "Bednet_Using",
    "Discard_Event": "Bednet_Discarded"
}

EMOD installation

Epidemiological MODeling software (EMOD) can be installed on computers running Windows (Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit)) or Linux (CentOS 7.1). For either operating system, there are relatively few prerequisites required and the EMOD executable (Eradication.exe) or Eradication binary for Linux is pre-built from the latest EMOD source code release. After completing installation, you can run simulations locally or on an HPC cluster using real-world data.

Note

If you want to download and modify the EMOD source code and build the Eradication.exe or Eradication binary for Linux yourself, see EMOD source code installation.

Install EMOD on Windows

To install EMOD on Windows computers, follow the steps below. You will install the pre-built Eradication.exe and all software necessary to run simulations locally. Optionally, you can install Python virtual environments, software to plot the output of simulations, and EMOD input files for various regions.

The EMOD executable (Eradication.exe) is tested using Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit). Windows HPC Server is used for testing remote simulations on a high-performance computing (HPC) cluster and the other Windows operating systems are used to test local simulations.

Note

If you want to download and modify the EMOD source code and build the Eradication.exe yourself, see EMOD source code installation.

Install EMOD

  1. Install the Microsoft HPC Pack 2019 Client Utilities Redistributable Package (64-bit). See https://www.microsoft.com/en-us/download/details.aspx?id=101361 for instructions.

  2. Install the Microsoft MPI v10. See https://www.microsoft.com/en-us/download/details.aspx?id=100593 for instructions, being sure to run the MSMpiSetup.exe file.

  3. Install the Microsoft Visual C++ 2022 Redistributable (64-bit). See https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist for instructions.

  4. On GitHub on the EMOD releases page, download the EMOD executable (Eradication.exe). Save to a local drive, such as the desktop.

Warning

Double-clicking Eradication.exe will not run the EMOD software or launch an installer. You must run EMOD from the command line or a script. See Running a simulation for more information.

(Optional) Install plotting software

None of the following plotting software is required to run simulations with EMOD, but it is useful for creating graphs from and evaluating the model output. In addition, EMOD provides many Python scripts for analyzing data.

Note

IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.

Python and Python packages

Python is required to install many of the software packages described below.

  1. In a web browser, go to https://www.python.org/downloads/release/python-399/ to install Python 3.9 64-bit.

  2. Scroll down and download one of the x86-64 bit installers (you may use the executable installer or the web-based installer.)

  3. Double-click the executable file and, in the installer window, select the Add Python 3.9 to PATH checkbox and click Customize installation.

  4. On the Optional Features window that opens, leave all default values selected and click Next. The Python package manager, pip, is used to install other Python packages.

  5. If you are running EMOD locally, IDM recommends that you select the Advanced Options window to customize the installation directory to “C:\Python39”.

    You may install Python in another location, but the Python plotting scripts included in the EMOD scenarios zip file assume that Python is installed directly under the C: drive. If you install it elsewhere, you may need to edit those scripts when using the scenarios to learn about EMOD functionality.

  6. Click Install. When installation is complete, click Close.

  7. To verify installation, open a Command Prompt window and type the following:

    python --version
Python virtual environments

Python virtual environments enable you to isolate your Python environments from one another and give you the option to run multiple versions of Python on the same computer. When using a virtual environment, you can indicate the version of Python you want to use and the packages you want to install, which will remain separate from other Python environments. You may use virtualenv, but venv is recommended and included with Python 3.3+.

  1. Navigate to the location where you want to create the virtual environment directory and enter the following to create a environment called “idm”, or other desired name:

    python -m venv idm

  2. To activate the virtual environment, enter the following:

    idm\Scripts\activate

  3. Verify that the command prompt displays “idm” at the beginning, which indicates that you are in the idm virtual environment. For example:

    (idm) my-computer:idm

  4. To verify you are using Python 3.9 64-bit, enter the following:

    python --version

  5. When you are done working in this virtual environment, deactivate the environment. The environment will be saved and you can reactivate it at any time. To deactivate, enter the following:

    deactivate
NumPy

We recommended that you download some of the NumPy Python package from http://www.lfd.uci.edu/~gohlke/pythonlibs, a page compiled by Christoph Gohlke, University of California, Irvine. The libraries there include linear algebra packages that are not included by default with the standard Windows packages. They are compiled Windows binaries, including the 64-bit versions required by EMOD. The naming convention used lists the Python version after “cp”, for example “cp39-cp39m”, and the Windows bit version after “win”, for example “win_amd64”.

The NumPy package adds support for large, multi-dimensional arrays and matrices to Python.

  1. Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy and select the WHL file for NumPy 1.22.1 (64-bit) that is compatible with Python 3.9 64-bit.

  2. Save the file to your Python installation directory.

  3. Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific NumPy WHL file you downloaded:

    pip install numpy-1.x.x+mkl-cp39-cp39m-win_amd64.whl
Python packages

The Python packages dateutil, six, and pyparsing provide text parsing and datetime functionality.

Note

Be sure NumPy is installed before you install Matplotlib.

  1. Open a Command Prompt window and enter the following:

    pip install python-dateutil
pip install pyparsing
pip install matplotlib
pip install future
R

R is a free software environment for statistical computing and graphics.

MATLAB

MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.

  1. Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2021b.

  2. If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2021b.

(Optional) Download input files

IDM provides input files that describe the demographics, migration patterns, and climate of many different locations across the world. You can download these files from the EMOD-InputData repository, which uses large file storage (LFS) to manage the binaries and large JSON (JavaScript Object Notation) files. A standard Git clone of the repository will only retrieve the metadata for these files managed with LFS. To retrieve the actual data, follow the steps below.

  1. Install the Git LFS plugin, if it is not already installed.

    • For Windows users, download the plugin from https://git-lfs.github.com.

    • For CentOS users, the plugin is included with the PrepareLinuxEnvironment.sh script.

  2. Using a Git client or Command Prompt window, clone the input data repository to retrieve the metadata:

    git clone https://github.com/InstituteforDiseaseModeling/EMOD-InputData.git

  3. Navigate to the directory where you downloaded the metadata for the input files.

  4. Download the actual data on your local machine:

    git lfs fetch

  5. Replace the metadata in the files with the actual data:

    git lfs checkout

Install EMOD on Linux

To install EMOD on Linux computers, follow the steps below. You will install the pre-built Eradication binary for Linux and all supporting software needed to run simulations locally. Optionally, you can install Python virtual environments, software to plot the output of simulations, and EMOD input files for various regions.

The Eradication binary for Linux is tested and supported on a CentOS 7.1 virtual machine on Azure. It has also been successfully built and run on Ubuntu, SUSE, and Arch, but has not been tested and is not supported on those Linux distributions.

Note

If you want to download and modify the EMOD source code and build the Eradication binary for Linux yourself, see EMOD source code installation.

Install EMOD using a script

The setup script installs most prerequisite software, including Python and the Python packages dateutil, six, pyparsing, NumPy, and matplotlib. Other prerequisites, such as Boost 1.77.0 and Microsoft MPI v10, are declared by the script as required. Because the installation instructions for these packages will vary based on the particular Linux distribution you are running, installation instructions are not included here.

Note

IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.

The script provides the option to install input files that describe the demographics, migration patterns, and climate of many different locations across the world. While the script installs a pre-built version of the Eradication binary for Linux, it also provides the option of installing the EMOD source code. For information on building the Eradication binary for Linux from source code, see EMOD source code installation.

Before you begin, you must have the following:

  • sudo privileges to install packages

  • 15 GB free in your home directory (if you install the EMOD source code and input files)

  • An Internet connection

  1. On GitHub on the EMOD releases page, download and run the PrepareLinuxEnvironment.sh script.

    Respond to the prompts for information while the script is running.

    1. Set the EMOD_ROOT environment variable to the path to the EMOD source path:

      EMOD_ROOT=~/IDM/EMOD

    2. Include Scripts and . in the path:

      export PATH=$PATH:.:$EMOD_ROOT/Scripts

    3. If you want to run simulations in the same session that you updated EMOD_ROOT and the Scripts path, reload the .bashrc file using source .bashrc.

  1. Download the Eradication binary for Linux for CentOS 7.1 (not Eradication.exe for Windows). See on EMOD releases on GitHub. Save to a local drive, such as the desktop.

(Optional) Install Python virtual environments

Python virtual environments enable you to isolate your Python environments from one another and give you the option to run multiple versions of Python on the same computer. When using a virtual environment, you can indicate the version of Python you want to use and the packages you want to install, which will remain separate from other Python environments. You may use virtualenv, but venv is recommended and included with Python 3.3+.

  1. Navigate to the location where you want to create the virtual environment directory and enter the following to create a environment called “idm”, or other desired name:

    python -m venv idm

  2. To activate the virtual environment, enter the following:

    source idm/bin/activate

  3. Verify that the command prompt displays “idm” at the beginning, which indicates that you are in the idm virtual environment. For example:

    (idm) my-computer:idm

  4. To verify you are using Python 3.9 64-bit, enter the following:

    python --version

  5. When you are done working in this virtual environment, deactivate the environment. The environment will be saved and you can reactivate it at any time. To deactivate it, enter the following:

    deactivate
(Optional) Install plotting software

None of the following plotting software is required to run simulations with EMOD, but they are useful for creating graphs from and evaluating the model output. In addition, EMOD provides many Python scripts for analyzing data.

R

R is a free software environment for statistical computing and graphics.

MATLAB

MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.

  1. Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2021b.

  2. If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2021b.

(Optional) Download input files

IDM provides input files that describe the demographics, migration patterns, and climate of many different locations across the world. You can download these files from the EMOD-InputData repository, which uses large file storage (LFS) to manage the binaries and large JSON (JavaScript Object Notation) files. A standard Git clone of the repository will only retrieve the metadata for these files managed with LFS. To retrieve the actual data, follow the steps below.

  1. Install the Git LFS plugin, if it is not already installed.

    • For Windows users, download the plugin from https://git-lfs.github.com.

    • For CentOS users, the plugin is included with the PrepareLinuxEnvironment.sh script.

  2. Using a Git client or Command Prompt window, clone the input data repository to retrieve the metadata:

    git clone https://github.com/InstituteforDiseaseModeling/EMOD-InputData.git

  3. Navigate to the directory where you downloaded the metadata for the input files.

  4. Download the actual data on your local machine:

    git lfs fetch

  5. Replace the metadata in the files with the actual data:

    git lfs checkout

Overview of EMOD software

The Institute for Disease Modeling (IDM) develops detailed simulations of disease transmission through the use of quantitative software modeling. The agent-based model, Epidemiological MODeling software (EMOD), helps determine the combination of health policies and intervention strategies that can lead to disease eradication. EMOD calculates how diseases may spread in particular areas and is used to analyze the effects of current and future health policies and intervention strategies. It supports infectious disease campaign planning, data gathering, new product development, and policy decisions. IDM shares this modeling software with the research community to advance the understanding of disease dynamics.

EMOD is quite different from a deterministic compartmental model, which uses an ordinary differential equation (ODE) to determine the rates at which proportions of the population move from each compartment (or disease state) to another. EMOD is an agent-based model (ABM) that simulates the simultaneous interactions of agents in an effort to recreate complex phenomena. Each agent, whether it is a human or a vector, can be assigned a variety of properties to represent age, gender, parasite density, and much more. Their behavior and interactions with one another are determined by using decision rules based on their properties. These models have strong predictive power and are able to leverage spatial and temporal dynamics.

EMOD is also stochastic, meaning that there is randomness built into the model. Infection and recovery processes are represented as probabilistic Bernoulli random draws. In other words, when a susceptible person comes into contact with a pathogen, they are not guaranteed to become infected. Instead, you can imagine flipping a coin that has a λ chance of coming up tails S(t) times and every person who gets a head is considered infected. This randomness better approximates what happens in reality. It also means that you must run many simulations to determine the probability of particular outcomes.

Simulation types

EMOD supports the following simulation types for modeling a variety of diseases:

  • Generic disease (GENERIC_SIM), which can be used for modeling a variety of diseases such as influenza or measles

  • Vector-borne diseases (VECTOR_SIM), which can be used for modeling vector-borne diseases such as dengue

  • Malaria (MALARIA_SIM), which adds features specific to malaria biology and treatment

  • Tuberculosis with HIV coinfection (TBHIV_SIM), which can be used for modeling TB transmission, with the option to add HIV coinfection as a contributing factor

  • Sexually transmitted infections (STI_SIM), which adds features for sexual relationship networks

  • HIV (HIV_SIM), which adds features specific to HIV biology and treatment

  • Environmental transmission (ENVIRONMENTAL_SIM), which adds features for diseases transmitted through contaminated food or water

  • Typhoid (TYPHOID_SIM), which adds features specific to typhoid biology and treatment

The illustration below shows how the simulation types are built upon one another. With a few exceptions, all parameters available to configure the simulation in the generic simulation type are inherited by the vector simulation type. The vector simulation type adds additional parameters specific to the biology of vector-borne diseases, which in turn are inherited by the malaria simulation type, which adds parameters specific to malaria biology and treatment, and so on. Therefore, depending on the simulation type you select, different parameters are available for you to use. In addition, simulation types for broader classes of disease can be extended to build your own disease-specific model.

_images/simulation-types.png

Simulation type inheritance

EMOD utilizes object-oriented programming design principles such as interfaces, factories, and observers to achieve a highly modular architecture, thus enabling comparisons of structural assumptions and different levels of model detail. For example, parameters specific to the intrahost biology of disease progression and to behavioral propensities that drive health care seeking have been separated into different inheritance classes. Thus, modules or sub-modules can be interchanged while leaving other portions of the model intact.

EMOD can produce statistically significant results over a broad set of parameters and scenarios. One strength of EMOD is the ability to incorporate interventions aimed at controlling or eradicating disease. Quantitative analysis of the simulated output enables disease eradication efforts to be more driven by data. The IDM research team has published many articles related to modeling and the modeling concepts underpinning EMOD. For a list of published articles, see IDM Publications.

This section provides an overview of EMOD and files needed to run simulations. The architecture diagram below shows, at a high level, how the system functions. If you run simulations in parallel on a multi-node cluster, there is also a Message Passing Interface (MPI) component used to pass data between multiple instances of EMOD.

_images/architecture.png

High-level EMOD system architecture

Input files

EMOD takes a number of files as inputs for running simulations. The input files indicate the transmission mode, population size, age distribution, disease interventions, and many more qualities that affect disease transmission. The EMOD executable (Eradication.exe) takes these input files and uses them to run a simulation of the disease dynamics.

Many of the input files are formatted as JSON (JavaScript Object Notation) files. JSON is a simple text format that uses key/value pairs to encode data. In EMOD, the key is a parameter name and the value is the setting for that parameter. For example, “Base_Incubation_Period”: 5 sets the incubation period for the disease being modeled to be five days. JSON files are easy to read and edit. For more information about JSON, see EMOD parameter reference. Some of the inputs are compiled binary files.

Primary files

The primary files used for EMOD simulations are the following:

demographics file

Defines the geography and the population being modeled. Each geographic node has a location, population, and certain characteristics assigned to it. These files are often reused across multiple simulations and disease scenarios.

configuration file

Defines many aspects of the simulation, including disease characteristics like infectivity and transmission mode and simulation characteristics like simulation length and additional input files to use.

campaign file

Defines the events that occur during the simulation. Primarily, these are the various disease interventions that will take place, but they also include the disease outbreaks.

Supplementary files

There are other optional files that EMOD can use as inputs to the simulation. These files are not necessary for every simulation or every disease. For example, climate files are only used for vector-borne diseases because weather affects mosquito populations. Migration files are only used for multi-node simulations where human or vector movement is important. Because EMOD is stochastic, it requires running many simulations which may require a lot of processing power. Load-balancing and serialization files are for managing computing resources.

These files use both a JSON file for metadata and an associated binary file that contains the actual data. You will typically use these input files in their default state.

Input file IDs

The Institute for Disease Modeling (IDM) provides collections of climate and demographics files for many different locations in the world for download on GitHub. For instructions, see EMOD installation. Some input files were prepared using CIESIN Gridded Population of the World (GPW) population distribution and a corresponding spatial resolution grid (for example, 2.5 arc minutes) to define the initial population and extent of the nodes for country-wide input files. Therefore, the naming convention for this files usually leads with the geographic location, followed by the spatial resolution, and input file type.

All input files except configuration and campaign files include the parameter IdReference in the metadata, which is used to generate the NodeID associated with each node in a simulation. The values for IdReference and NodeID must be the same across all input files used in a simulation. See Demographics parameters for more information about NodeID generation.

Demographics file

Demographics files are JSON-formatted files that contain information on the demographics of the population in each node in the simulation. For example, the longitude and latitude, the number of individuals, and the distribution for age, gender, immunity, risk, and mortality. Once you have it configured for a given population and location, you will likely reuse it across many different simulation scenarios.

In addition, demographics files are useful for creating heterogeneity a population. You can define values for accessibility, age bins, geography, risk, and other properties and assign values to individuals or nodes. For example, you might want to divide a population up into different bins based on age so you can target interventions to individuals in a particular age range. Another common use is to configure treatment coverage to be higher for individuals in easily accessible regions and lower for individuals in areas that are difficult to access. for more information, see Individual and node properties.

You can also simulate a complex health care system using property values that represent the intervention status for each individual. For example, consider a disease that has a second-line treatment that is not used unless the first-line treatment has proven ineffective. You can assign a property value after receiving the first-line treatment and prevent anyone from receiving the second-line treatment unless they have that property value and are still symptomatic. For more information, see Cascade of care.

EMOD assumes homogeneous mixing and disease transmission for the generic simulation type. Using the individual properties in the demographics file, you can also use the HINT feature to add heterogeneous transmission to your generic model. You cannot manually configure heterogeneous transmission using HINT with other simulation types because the heterogeneity in transmission for specific diseases and disease classes is configured by transmission parameters specific to each disease model. For more information, see Property-based heterogeneous disease transmission (HINT).

You do have the option to run a simulation without a demographics file if you set Enable_Demographics_Builtin to 1 in the configuration file. However, this option is primarily used for software testing. It will not provide meaningful simulation data as it does not represent the population of a real geographic location.

The demographics file structure and parameters are described in more detail in Demographics parameters.

Demographics overlay files

You can specify multiple demographics files, which function as a “base layer” file and one or more “overlay” files that override the base layer configuration. Overlay files can change the value of parameters already specified in the base layer or add new parameters. Support for multiple demographics layers allows for the following scenarios:

  • Separating different sets of parameters and values into individual layers (for example, to separate those that are useful for specific diseases into different layers)

  • Adding new parameters for a simulation into a new layer for easier prototyping

  • Overriding certain parameters of interest in a new layer

  • Overriding certain parameters for a particular sub-region

  • Simulating subsets of a larger region for which input files have been constructed

To use an overlay file:

  1. Select the demographics file to use as the base layer file. All nodes to be included in the simulation must be listed in this file.

  2. In the metadata, make note of the IdReference value.

    You may change this value if you desire, but all input files for a simulation must have the same IdReference value. For more information about this parameter and the structure of demographics files in general, see Demographics parameters.

  3. Create one or more overlay files. Keep the following things in mind:

    • In the metadata, the value for IdReference must match the value in the base layer file and all other input files except configuration and campaign.

    • Any nodes listed in an overlay but not in the base layer will not be simulated.

    • If the demographics files include any JSON array elements, the entire array is overridden. You cannot add or remove individual elements in an array using an overlay file.

    • Overriding a parameter value on a node will not affect the other parameter values applied to that node.

    • Values set in the Defaults section of an overlay will be applied to all nodes listed in that file, not all nodes in the entire simulation. Therefore, an overlay file that includes a Defaults section but no Nodes section will not have any effect.

  4. Place all demographics files in the directory where the other input files are stored.

  5. In the configuration file, set Demographics_Filenames to an array that contains a comma-delimited list of demographics files, listing the base layer file first.

An example base layer demographics file and an overlay file is below. You can see that the overlay adds the TransmissionMatrix for Heterogeneous Intra-Node Transmission (HINT) to only three of the five nodes (which correspond to Washington state counties).

{
    "Metadata": {
        "Author": "ewenger",
        "NodeCount": 5,
        "Tool": "table_to_demographics.py",
        "IdReference": "SampleContent",
        "DateCreated": "2013-08-01 15:37:16.853000"
    },
    "Defaults": {
        "NodeAttributes": {
            "BirthRate_DESCRIPTION": "Replacement of stable age distribution: Birth_Rate_Dependence=DEMOGRAPHIC_DEP_RATE (i.e. 14-45 year-old PossibleMothers)",
            "BirthRate": 0.00017675,

            "Airport": 0,
            "Region": 1,
            "Altitude": 0,
            "Seaport": 0
        },
        "IndividualAttributes": {

            "AgeDistribution_DESCRIPTION": "Box between age 0 and 60 years: Age_Initialization_Distribution_Type=DISTRIBUTION_SIMPLE",
            "AgeDistributionFlag": 1,
            "AgeDistribution1": 0,
            "AgeDistribution2": 21900,

            "PrevalenceDistribution_DESCRIPTION": "No initial infections",
            "PrevalenceDistributionFlag": 0,
            "PrevalenceDistribution1": 0,
            "PrevalenceDistribution2": 0,

            "RiskDistributionFlag": 0,
            "RiskDistribution1": 1,
            "RiskDistribution2": 0,

            "SusceptibilityDistributionFlag": 0,
            "SusceptibilityDistribution1": 1,
            "SusceptibilityDistribution2": 0,

            "MigrationHeterogeneityDistributionFlag": 0,
            "MigrationHeterogeneityDistribution1": 1,
            "MigrationHeterogeneityDistribution2": 0,

            "MortalityDistribution_DESCRIPTION": "WA state (1999-2010).  Source: wonder.cdc.gov",
            "MortalityDistribution": {
                "NumDistributionAxes": 2,
                "AxisNames": [ "gender", "age" ],
                "AxisUnits": [ "male=0,female=1", "years" ],
                "AxisScaleFactors": [ 1, 365 ],
                "NumPopulationGroups": [ 2, 15 ],
                "PopulationGroups": [
                    [ 0, 1 ],
                    [ 0, 1, 2.5, 7.5, 12.5, 17.5, 22.5, 30, 40, 50, 60, 70, 80, 90, 120 ]
                ],
                "ResultUnits": "annual deaths per 1000 individuals",
                "ResultScaleFactor": 0.00000273972602739726027397260273973,
                "ResultValues": [
                    [ 4.8, 0.2, 0.1, 0.2, 0.5, 1.1, 1.1, 1.7, 4.1, 9.2, 19.8, 53.7, 154.2, 1000, 1000 ],
                    [ 4.2, 0.2, 0.2, 0.2, 0.2, 0.4, 0.5, 1.1, 2.6, 5.5, 14.3, 40.1, 129.3, 1000, 1000 ]
                ]
            }
        }
    },
    "Nodes": [
        {
            "County": "Adams",
            "NodeAttributes": {
                "Latitude": 47.1274,
                "InitialPopulation": 19200,
                "Longitude": -118.38
            },
            "NodeID": 1
        },
        {
            "County": "Asotin",
            "NodeAttributes": {
                "Latitude": 46.3393,
                "InitialPopulation": 21800,
                "Longitude": -117.0482
            },
            "NodeID": 2
        },
        {
            "County": "Benton",
            "NodeAttributes": {
                "Latitude": 46.2068,
                "InitialPopulation": 183400,
                "Longitude": -119.7689
            },
            "NodeID": 3
        },
        {
            "County": "Chelan",
            "NodeAttributes": {
                "Latitude": 47.4235,
                "InitialPopulation": 73600,
                "Longitude": -120.3103
            },
            "NodeID": 4
        },
        {
            "County": "Clallam",
            "NodeAttributes": {
                "Latitude": 48.1181,
                "InitialPopulation": 72350,
                "Longitude": -123.4307
            },
            "NodeID": 5
        }
    ]
}

{
    "Metadata": {
        "Author": "cwiswell",
        "NodeCount": 10,
        "Tool": "table_to_demographics.py",
        "IdReference": "SampleContent",
        "DateCreated": "2013-08-01 15:37:16.853000"
    },
    "Defaults": {
        "IndividualProperties": [
            {
                "Property": "Accessibility",
                "Values": [ "VaccineTake", "VaccineRefuse"],
                "Initial_Distribution": [ 0.85, 0.15],
                "TransmissionMatrix": {
                    "Route": "Contact",
                    "Matrix": [
                        [1.1, 0.3],
                        [0.3, 5.0]
                    ]
                }
            },
            {
                "Property": "Age_Bin",
                "Age_Bin_Edges_In_Years": [ 0, 5, 13, -1 ],
                "TransmissionMatrix": {
                    "Route": "Contact",
                    "Matrix": [
                        [1.4, 1.0, 1.0],
                        [1.0, 2.5, 0.7],
                        [1.0, 0.7, 1.0]
                    ]
                }
            }
        ]
    },
    "Nodes": [
        {
            "NodeID": 1
        },
        {
            "NodeID": 3
        },
        {
            "NodeID": 5
        }
    ]
}
Configuration file

The primary means of configuring the disease simulation is the configuration file. This required file is a JSON (JavaScript Object Notation) formatted file that is typically named config.json. The configuration file controls many different aspects of the simulation. For example,

  • The names of the campaign file and other input files to use

  • How to use additional demographics, climate, and migration data (such as enabling features or scaling values)

  • General disease attributes such as infectivity, immunity, mortality, and so on

  • Attributes specific to the disease type being modeled, such as infectivity and mortality

  • The reports to output from the simulation

Although you can create configuration files entirely from scratch, it is often easier to start from an existing configuration file and modify it to meet your needs. You can download sets of configuration and campaign files that illustrate how to model different disease scenarios at EMOD scenarios. For more information, see Tutorials and simulation examples.

The simplest method of working with the configuration files is to use a text editor to directly edit the parameters or parameter values in the JSON file. However, you may want to use Python or another scripting language to make large modifications. See Example scripts to modify a configuration file for more information.

For a complete list of configuration parameters that are available to use with this simulation type, see Configuration parameters. For more information about JSON, see EMOD parameter reference.

Flattened configuration files

A flattened configuration file is generally a single-depth JSON file with configuration parameters listed alphabetically. This is the configuration file format that Eradication.exe and Eradication binary for Linux both require for running simulations.

Below is an example of a flattened configuration file:

{
  "parameters": {
    "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
    "Base_Infectivity": 0.3,
    "Climate_Model": "CLIMATE_OFF",
    "Config_Name": "1_Generic_MinimalConfig",
    "Custom_Reports_Filename": "",
    "Default_Geography_Initial_Node_Population": 100,
    "Default_Geography_Torus_Size": 3,
    "Enable_Default_Reporting": 1,
    "Enable_Demographics_Builtin": 1,
    "Enable_Demographics_Reporting": 0,
    "Enable_Demographics_Risk": 0,
    "Enable_Disease_Mortality": 0,
    "Enable_Heterogeneous_Intranode_Transmission": 0,
    "Enable_Immunity": 0,
    "Enable_Initial_Prevalence": 0,
    "Enable_Initial_Susceptibility_Distribution": 0,
    "Enable_Interventions": 0,
    "Enable_Maternal_Infection_Transmission": 0,
    "Enable_Maternal_Protection": 0,
    "Enable_Property_Output": 0,
    "Enable_Skipping": 0,
    "Enable_Spatial_Output": 0,
    "Enable_Superinfection": 0,
    "Enable_Susceptibility_Scaling": 0,
    "Enable_Vital_Dynamics": 0,
    "Geography": "NONE",
    "Incubation_Period_Constant": 3,
    "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Individual_Sampling_Type": "TRACK_ALL",
    "Infection_Updates_Per_Timestep": 1,
    "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Exponential": 7,    
    "Listed_Events": [],
    "Load_Balance_Filename": "",
    "Maternal_Infection_Transmission_Probability": 0,
    "Migration_Model": "NO_MIGRATION",
    "Node_Grid_Size": 0.042,
    "Number_Basestrains": 1,
    "Number_Substrains": 1,
    "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
    "Population_Scale_Type": "USE_INPUT_FILE",
    "Report_Event_Recorder": 0,
    "Run_Number": 1,
    "Simulation_Duration": 180,
    "Simulation_Timestep": 1,
    "Simulation_Type": "GENERIC_SIM",
    "Start_Time": 0,
    "Symptomatic_Infectious_Offset": 0
  }
}
Hierarchical configuration files

A hierarchical file allows you to organize parameters into logical groups by nesting them within JSON objects, making them easier to manage. If you use hierarchical configuration files, you must flatten them prior to running a simulation. The names you use to label these logical categories are unimportant; the scripts used to flatten the files will search through the hierarchies and retain only the “leaf” values in the resulting flattened file. See Configuration overlay files for more information on flattening files.

Below is an example of a hierarchical configuration file:

{
  "parameters": {
    "CAMPAIGNS": {
      "Campaign_Filename": "campaign.json",
      "Enable_Interventions": 1,
      "Listed_Events": [],
      "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT"
    },
    "CLIMATE": {
      "Climate_Model": "CLIMATE_OFF"
    },
    "DEMOGRAPHICS": {
      "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
      "Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE",
      "Birth_Rate_Time_Dependence": "NONE",
      "Default_Geography_Initial_Node_Population": 1000,
      "Default_Geography_Torus_Size": 10,
      "Demographics_Filenames": [
        "NO_DEFAULT_DEMOGRAPHICS"
      ],
      "Enable_Aging": 1,
      "Enable_Birth": 1,
      "Enable_Demographics_Birth": 0,
      "Enable_Demographics_Builtin": 0,
      "Enable_Demographics_Reporting": 0,
      "Enable_Demographics_Risk": 0,
      "Enable_Natural_Mortality": 1,
      "Enable_Vital_Dynamics": 1,
      "IMMUNITY": {
        "Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
        "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
        "Enable_Immune_Decay": 1,
        "Enable_Immunity": 1,
        "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
        "Post_Infection_Acquisition_Multiplier": 0,
        "Post_Infection_Transmission_Multiplier": 0,
        "Susceptibility_Scaling_Type": "CONSTANT_SUSCEPTIBILITY",
        "Transmission_Blocking_Immunity_Decay_Rate": 0.1,
        "Transmission_Blocking_Immunity_Duration_Before_Decay": 60
      },
      "MORTALITY": {
        "Base_Mortality": 0,
        "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER",
        "Enable_Disease_Mortality": 0,
        "Mortality_Blocking_Immunity_Decay_Rate": 0.001,
        "Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
        "Mortality_Time_Course": "DAILY_MORTALITY",
        "Post_Infection_Mortality_Multiplier": 0
      },
      "Minimum_Adult_Age_Years": 15,
      "Population_Density_C50": 30,
      "Population_Scale_Type": "USE_INPUT_FILE",
      "SAMPLING": {
        "Base_Individual_Sample_Rate": 1,
        "Individual_Sampling_Type": "TRACK_ALL",
        "Max_Node_Population_Samples": 40,
        "Sample_Rate_0_18mo": 1,
        "Sample_Rate_10_14": 1,
        "Sample_Rate_15_19": 1,
        "Sample_Rate_18mo_4yr": 1,
        "Sample_Rate_20_Plus": 1,
        "Sample_Rate_5_9": 1,
        "Sample_Rate_Birth": 2
      },
      "x_Base_Population": 1
    },
    "DISEASE": {
      "Enable_Superinfection": 0,
      "INCUBATION": {
        "Incubation_Period_Constant": 3,
        "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION"
      },
      "INFECTIOUSNESS": {
        "Base_Infectivity": 0.3,
        "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
        "Infectious_Period_Exponential": 7,        
        "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY"
      },
      "Infection_Updates_Per_Timestep": 1,
      "Max_Individual_Infections": 1,
      "TRANSMISSION": {
        "Enable_Maternal_Infection_Transmission": 0,
        "Maternal_Transmission_Probability": 0
      }
    },
    "FUDGE_FACTORS": {
      "x_Air_Migration": 1,
      "x_Birth": 1,
      "x_Local_Migration": 1,
      "x_Other_Mortality": 1,
      "x_Regional_Migration": 1,
      "x_Sea_Migration": 1,
      "x_Temporary_Larval_Habitat": 1
    },
    "HPC": {
      "Load_Balance_Filename": ""
    },
    "INTRANODE_TRANSMISSION": {
      "Enable_Heterogeneous_Intranode_Transmission": 0
    },
    "MIGRATION": {
      "Migration_Model": "NO_MIGRATION"
    },
    "OUTPUT": {
      "Custom_Reports_Filename": "NoCustomReports",
      "Enable_Default_Reporting": 1,
      "Enable_Property_Output": 0,
      "Enable_Spatial_Output": 0,
      "Report_Event_Recorder": 0
    },
    "POLIO": {},
    "PRIMARY": {
      "Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET",
      "ENUMS": {
        "Simulation_Type": "GENERIC_SIM"
      },
      "Node_Grid_Size": 0.042,
      "Run_Number": 0,
      "Simulation_Duration": 365,
      "Simulation_Timestep": 1,
      "Start_Time": 0
    },
    "STRAIN_TRACKING": {
      "Number_Basestrains": 1,
      "Number_Substrains": 1
    },
    "Symptomatic_Infectious_Offset": 0
  }
}
Configuration overlay files

You can use two configuration files when setting up a simulation. One file contains default parameter settings and an overlay file contains additional parameters or different parameter values that override the values in the default file.

Overlay files allow you to easily separate a subset of parameters that are of particular interest from the rest of the parameters needed to run a simulation. You can easily modify the parameters in the overlay file without needing to maintain a complete configuration file. This can be especially helpful when you want to experiment with the values set in certain parameters of interest without modifying the rest of the settings. You can have one default file and many different overlay files for different configurations. It also allows you to easily update the default values across multiple simulations.

These files must be flattened into a single file and the values in the overlay file will override those in the default file. When using overlay files, the parameters are often organized into logical groups using the hierarchical file format. See Configuration file for more information. When using any kind of hierarchical file, whether or not you are using an overlay file, it must also be flattened using the Python script below.

To flatten two configuration files:

  1. Create the default configuration file in JSON. You may, though it is not required, organize the parameters into logical categories of nested JSON objects to make managing the parameters easier. See Configuration parameters for a complete list of all parameters that are available. See the example default configuration file below.

    {
  "parameters": {
    "CAMPAIGNS": {
      "Campaign_Filename": "campaign.json",
      "Enable_Interventions": 1,
      "Listed_Events": [],
      "PKPD_Model": "FIXED_DURATION_CONSTANT_EFFECT"
    },
    "CLIMATE": {
      "Climate_Model": "CLIMATE_OFF"
    },
    "DEMOGRAPHICS": {
      "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
      "Birth_Rate_Dependence": "DEMOGRAPHIC_DEP_RATE",
      "Birth_Rate_Time_Dependence": "NONE",
      "Default_Geography_Initial_Node_Population": 1000,
      "Default_Geography_Torus_Size": 10,
      "Demographics_Filenames": [
        "NO_DEFAULT_DEMOGRAPHICS"
      ],
      "Enable_Aging": 1,
      "Enable_Birth": 1,
      "Enable_Demographics_Birth": 0,
      "Enable_Demographics_Builtin": 0,
      "Enable_Demographics_Reporting": 0,
      "Enable_Demographics_Risk": 0,
      "Enable_Natural_Mortality": 1,
      "Enable_Vital_Dynamics": 1,
      "IMMUNITY": {
        "Acquisition_Blocking_Immunity_Decay_Rate": 0.1,
        "Acquisition_Blocking_Immunity_Duration_Before_Decay": 60,
        "Enable_Immune_Decay": 1,
        "Enable_Immunity": 1,
        "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_OFF",
        "Post_Infection_Acquisition_Multiplier": 0,
        "Post_Infection_Transmission_Multiplier": 0,
        "Susceptibility_Scaling_Type": "CONSTANT_SUSCEPTIBILITY",
        "Transmission_Blocking_Immunity_Decay_Rate": 0.1,
        "Transmission_Blocking_Immunity_Duration_Before_Decay": 60
      },
      "MORTALITY": {
        "Base_Mortality": 0,
        "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER",
        "Enable_Disease_Mortality": 0,
        "Mortality_Blocking_Immunity_Decay_Rate": 0.001,
        "Mortality_Blocking_Immunity_Duration_Before_Decay": 60,
        "Mortality_Time_Course": "DAILY_MORTALITY",
        "Post_Infection_Mortality_Multiplier": 0
      },
      "Minimum_Adult_Age_Years": 15,
      "Population_Density_C50": 30,
      "Population_Scale_Type": "USE_INPUT_FILE",
      "SAMPLING": {
        "Base_Individual_Sample_Rate": 1,
        "Individual_Sampling_Type": "TRACK_ALL",
        "Max_Node_Population_Samples": 40,
        "Sample_Rate_0_18mo": 1,
        "Sample_Rate_10_14": 1,
        "Sample_Rate_15_19": 1,
        "Sample_Rate_18mo_4yr": 1,
        "Sample_Rate_20_Plus": 1,
        "Sample_Rate_5_9": 1,
        "Sample_Rate_Birth": 2
      },
      "x_Base_Population": 1
    },
    "DISEASE": {
      "Enable_Superinfection": 0,
      "INCUBATION": {
        "Incubation_Period_Constant": 3,
        "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION"
      },
      "INFECTIOUSNESS": {
        "Base_Infectivity": 0.3,
        "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
        "Infectious_Period_Exponential": 7,        
        "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY"
      },
      "Infection_Updates_Per_Timestep": 1,
      "Max_Individual_Infections": 1,
      "TRANSMISSION": {
        "Enable_Maternal_Infection_Transmission": 0,
        "Maternal_Transmission_Probability": 0
      }
    },
    "FUDGE_FACTORS": {
      "x_Air_Migration": 1,
      "x_Birth": 1,
      "x_Local_Migration": 1,
      "x_Other_Mortality": 1,
      "x_Regional_Migration": 1,
      "x_Sea_Migration": 1,
      "x_Temporary_Larval_Habitat": 1
    },
    "HPC": {
      "Load_Balance_Filename": ""
    },
    "INTRANODE_TRANSMISSION": {
      "Enable_Heterogeneous_Intranode_Transmission": 0
    },
    "MIGRATION": {
      "Migration_Model": "NO_MIGRATION"
    },
    "OUTPUT": {
      "Custom_Reports_Filename": "NoCustomReports",
      "Enable_Default_Reporting": 1,
      "Enable_Property_Output": 0,
      "Enable_Spatial_Output": 0,
      "Report_Event_Recorder": 0
    },
    "POLIO": {},
    "PRIMARY": {
      "Config_Name": "DEFAULT_CONFIG_NAME_SHOULD_BE_SET",
      "ENUMS": {
        "Simulation_Type": "GENERIC_SIM"
      },
      "Node_Grid_Size": 0.042,
      "Run_Number": 0,
      "Simulation_Duration": 365,
      "Simulation_Timestep": 1,
      "Start_Time": 0
    },
    "STRAIN_TRACKING": {
      "Number_Basestrains": 1,
      "Number_Substrains": 1
    },
    "Symptomatic_Infectious_Offset": 0
  }
}

  2. Create the overlay configuration file in JSON. This file must include the parameter Default_Config_Path, set to the path to the default configuration file, relative to the location of the flatten_config.py script in the EMOD Regression folder. Again, you may organize the parameters into logical categories if you desire. See the example overlay configuration file below.

    {
     "Default_Config_Path": "defaults/generic-default-config.json",
     "parameters": {
          "DEMOGRAPHICS": {
              "Enable_Demographics_Builtin": 0,
              "Birth_Rate_Dependence": "POPULATION_DEP_RATE",
              "Death_Rate_Dependence" : "NOT_INITIALIZED",
              "Enable_Vital_Dynamics": 0,
              "Sample_Rate_Birth": 1,
              "Enable_Demographics_Reporting": 1
          },
          "DISEASE": {
              "Base_Incubation_Period": 0,
              "Base_Infectious_Period": 4,
              "Base_Infectivity": 3.5,
              "Enable_Immune_Decay": 0
          },
          "PRIMARY": {
               "Config_Name": "00_Generic_DEFAULT",
               "Demographics_Filenames": ["demographics.json"],
               "Geography": "",
               "Run_Number": 1,
               "Simulation_Duration": 90
          }
     }
}

  3. In a Command Prompt window, navigate to the Regression folder.

  4. Run the flatten_config.py script, providing the relative path to the overlay file:

    python flatten_config.py experiment/parameter_overrides.json

  5. Open the resulting config.json file in the same folder as parameter_overrides.json and see that it has been flattened into a single layer with all parameters listed alphabetically and any logical categories removed. Eradication.exe will not accept a configuration file with nested JSON objects.

    {
  "parameters": {
    "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE",
    "Base_Infectivity": 0.3,
    "Climate_Model": "CLIMATE_OFF",
    "Config_Name": "1_Generic_MinimalConfig",
    "Custom_Reports_Filename": "",
    "Default_Geography_Initial_Node_Population": 100,
    "Default_Geography_Torus_Size": 3,
    "Enable_Default_Reporting": 1,
    "Enable_Demographics_Builtin": 1,
    "Enable_Demographics_Reporting": 0,
    "Enable_Demographics_Risk": 0,
    "Enable_Disease_Mortality": 0,
    "Enable_Heterogeneous_Intranode_Transmission": 0,
    "Enable_Immunity": 0,
    "Enable_Initial_Prevalence": 0,
    "Enable_Initial_Susceptibility_Distribution": 0,
    "Enable_Interventions": 0,
    "Enable_Maternal_Infection_Transmission": 0,
    "Enable_Maternal_Protection": 0,
    "Enable_Property_Output": 0,
    "Enable_Skipping": 0,
    "Enable_Spatial_Output": 0,
    "Enable_Superinfection": 0,
    "Enable_Susceptibility_Scaling": 0,
    "Enable_Vital_Dynamics": 0,
    "Geography": "NONE",
    "Incubation_Period_Constant": 3,
    "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Individual_Sampling_Type": "TRACK_ALL",
    "Infection_Updates_Per_Timestep": 1,
    "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Exponential": 7,    
    "Listed_Events": [],
    "Load_Balance_Filename": "",
    "Maternal_Infection_Transmission_Probability": 0,
    "Migration_Model": "NO_MIGRATION",
    "Node_Grid_Size": 0.042,
    "Number_Basestrains": 1,
    "Number_Substrains": 1,
    "Population_Density_Infectivity_Correction": "CONSTANT_INFECTIVITY",
    "Population_Scale_Type": "USE_INPUT_FILE",
    "Report_Event_Recorder": 0,
    "Run_Number": 1,
    "Simulation_Duration": 180,
    "Simulation_Timestep": 1,
    "Simulation_Type": "GENERIC_SIM",
    "Start_Time": 0,
    "Symptomatic_Infectious_Offset": 0
  }
}
Example scripts to modify a configuration file

Direct editing of the configuration file in a text editor may be sufficient for small and infrequent changes, but you will likely find that scripting tools are more powerful and reliable for both creating and modifying files.

The following example shows how to read a configuration file to a Python dictionary, modify a parameter, and write it back out to the file:

import json

# load the current config.json
config_file = open( "config.json" )
config_json = json.load( config_file )
config_file.close()

# modify one of the parameter values, e.g. "base_infectivity"
config_json["parameters"]["base_infectivity"] = 0.5

# write the modified config file
modified_file = open( "modified_config.json", "w" )
json.dump( config_json, modified_file, sort_keys=True, indent=4 )
modified_file.close()

The following example shows how to modify a configuration file in MATLAB:

addpath Matlab
addpath Matlab\test

% load the simulation configuration file into MATLAB structure
configjson = loadJson( "config.json" );

% modify one of the values
configjson.parameters.Base_Infectivity = 08.5;

% save the new configuration to file
saveJson( "modified_config.json", configjson );
Parameter sweeps

Parameter sweeps iteratively update the values of parameters to exhaustively search through the parameter space for a simulation. EMOD does not currently support automated parameter sweeps. However, you can write your own code, such as a Python or MATLAB script, that iterates through the values you want for a particular parameter. This topic describes how to perform a parameter sweep.

For example, you can run simulations using a Python script that uses the parameter values specified in a JSON parameter sweep file to iteratively update the configuration or campaign parameter values. The IDM test team performs parameter sweeps as part of regression testing. See the following examples to see how this is implemented.

The following JSON example illustrates sweeping through configuration parameter values.

{
    "sweep" :
    {
        "path": "43_Vector_Garki_MultiCore_VectorMigration",
        "param_name" : "Run_Number",
        "param_values" : [ 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144 ]
    }
}

The following Python example illustrates how to update the configuration file with the above values. This is excerpted from the regression_test.py script in the Regression directory.

elif "sweep" in reglistjson:
    print( "Running sweep...\n" )
    param_name = reglistjson["sweep"]["param_name"]

    for param_value in reglistjson["sweep"]["param_values"]:
        os.chdir(ru.cache_cwd)
        sim_timestamp = str(datetime.datetime.now()).replace('-', '_' ).replace( ' ', '_' ).replace( ':', '_' ).replace( '.', '_' )
        if regression_id == None:
            regression_id = sim_timestamp

        configjson = ru.flattenConfig( os.path.join( reglistjson["sweep"]["path"], "param_overrides.json" ) )
        if configjson is None:
            print("Error flattening config.  Skipping " + simcfg["path"])
            ru.final_warnings += "Error flattening config.  Skipped " + simcfg["path"] + "\n"
            continue

        # override sweep parameter
        configjson["parameters"][param_name] = param_value

        campjson_file = open( os.path.join( reglistjson["sweep"]["path"],"campaign.json" ) )
        campjson = json.loads( campjson_file.read().replace( "u'", "'" ).replace( "'", '"' ).strip( '"' ) )
        campjson_file.close()
        configjson["campaign_json"] = str(campjson)

        report_fn = os.path.join( reglistjson["sweep"]["path"],"custom_reports.json" )
        if os.path.exists( report_fn ) == True:
            reportjson_file = open( report_fn )
            reportjson = json.loads( reportjson_file.read().replace( "u'", "'" ).replace( "'", '"' ).strip( '"' ) )
            reportjson_file.close()
            configjson["custom_reports_json"] = str(reportjson)
        else:
            configjson["custom_reports_json"] = None

        thread = runner.commissionFromConfigJson( sim_timestamp, configjson, reglistjson["sweep"]["path"], None, 'sweep' )
        ru.reg_threads.append( thread )
else:
    print "Unknown state"
    sys.exit(0)
Campaign file

The campaign file is an optional JSON (JavaScript Object Notation) file that distributes outbreaks and contains all parameters that define the collection of interventions that make up a disease control or eradication campaign. For example, campaign parameters can control the following:

  • Size and location of outbreaks

  • Target demographic (age, location, gender, etc.) for interventions

  • Diagnostic tests to use

  • The cost and timing of interventions

Much of the power and flexibility of EMOD comes from the customizable campaign interventions. Briefly, campaigns are created through the hierarchical organization of parameter groups. It is hierarchically organized into logical groups of parameters that can have arbitrary levels of nesting. Typically, the file is named campaign.json. The relative path to this file is specified by Campaign_Filename in the configuration file.

To distribute an intervention, you must configure the following nested JSON objects:

campaign event

Campaign events determine when and where an intervention is distributed during a campaign. “When” can be the number of days after the beginning of the simulation or at a point during a particular calendar year. “Where” is the geographic node or nodes in which the event takes place.

event coordinator

Event coordinators are nested within the campaign event JSON object and determine who receives the intervention. “Who” is determined by filtering on age, gender, or on the individual properties configured in the demographics files, such as risk group or sociodemographic category. See Individual and node properties.

individual-level intervention

Individual-level interventions determine what will be distributed to individuals to reduce the spread of a disease. For example, distributing vaccines or drugs are individual-level interventions. In the schema, these are labeled as IndividualTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births (the individual’s own birth), GaveBirth, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

Individual-level interventions can be used as part of configuring a cascade of care along with the individual properties set in the demographics file. Use Disqualifying_Properties to disqualify individuals who would otherwise receive the intervention and New_Property_Value to assign a new value when the intervention is received. For example, you can assign a property value after receiving the first-line treatment for a disease and prevent anyone from receiving the second-line treatment unless they have that property value and are still symptomatic.

node-level intervention

Node-level interventions determine what will be distributed to each node to reduce the spread of a disease. For example, spraying larvicide in a village to kill mosquito larvae is a node-level malaria intervention. Sometimes this can be an intermediate intervention that schedules another intervention. Node-level disease outbreaks are also configured as “interventions”. In the schema, these are labeled as NodeTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

Creating campaigns describes some ways to configure a campaign file to target individuals with particular characteristics, repeat interventions, and more. See Campaign parameters for a comprehensive list and description of all parameters available to use in the campaign file for this simulation type.

Although you can create campaign files entirely from scratch, it is often easier to start from an existing campaign file and modify it to meet your needs. You can download sets of configuration and campaign files that illustrate how to model different disease scenarios at EMOD scenarios. For more information, see Tutorials and simulation examples.

Campaign overlay files

You can use two campaign files when setting up a simulation. One file contains default campaign settings and an overlay file contains additional parameters or different parameter values that override the values in the default file. The files must be flattened into a single file before running a simulation.

Overlay files allow you to easily separate a subset of parameters that are of particular interest from the rest of the parameters needed to run a simulation. You can easily modify the parameters in the overlay file without needing to maintain a complete campaign file. This can be especially helpful when you want to experiment with different interventions without modifying the rest of the settings. You can have one default file and many different overlay files for different intervention settings. It also allows you to easily update the default values across multiple simulations.

In addition to being used for model experimentation, overlay files are used when testing the software functionality after making source code changes. If you run the EMOD regression tests using regression_test.py, campaign files will be flattened as part of those tests. However, this may take several hours if run locally. More guidance on modifying the EMOD source code is in the “Advance the model” section.

The EMOD Regression directory contains many different subdirectories that contain configuration, campaign, and other associated files to run simulations used in regression testing. Some subdirectories include a campaign overlay file (campaign_overrides.json), which has been created by combining campaign_overrides.json with one of the default files in Regression/defaults. The naming of these files is an arbitrary convention used at IDM; you may name this files anything you choose. However, it may be useful to see some examples of these files to understand how they are used.

To flatten campaign files:

  1. Create the default campaign file in JSON. You may, though it is not required, organize the parameters into logical categories of nested JSON objects to make managing the parameters easier. See Campaign parameters for a complete list of all parameters that are available. See the example default campaign file below.

    {
    "Campaign_Name": "Initial Seeding",
    "Use_Defaults": 1,
    "Events": [
        {
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "Antigen": 0,
                    "Genome": 0,
                    "Outbreak_Source": "PrevalenceIncrease",
                    "class": "OutbreakIndividual"
                }
            }
        }
    ]
}

  2. Create the overlay campaign file in JSON. This file must include the parameter Default_Campaign_Path, set to the path to the default campaign file, relative to the location of the flatten_campaign.py script in the EMOD Regression folder. Again, you may organize these into logical categories if you desire. See the example overlay campaign file below.

    {
    "Campaign_Name": "Vaccine",
    "Default_Campaign_Path": "defaults/generic-default-campaign.json",
    "Events": [
        {
            "VACCINATION": "BEGIN",
            "Event_Name": "SimpleVaccine",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.5,
                "Intervention_Config": {
                    "Cost_To_Consumer": 10,
                    "Waning_Config": {
                        "class": "WaningEffectMapLinear",
                        "Initial_Effect" : 1.0,
                        "Expire_At_Durability_Map_End" : 0,
                        "Durability_Map" :
                        {
                            "Times"  : [   0,  30,  60,  90, 120 ],
                            "Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ]
                        }
                    },
                    "Vaccine_Take": 1,
                    "Vaccine_Type": "AcquisitionBlocking",
                    "class": "SimpleVaccine"
                },
                "Number_Repetitions": 3,
                "Target_Demographic": "Everyone",
                "Timesteps_Between_Repetitions": 7,
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 1,
            "class": "CampaignEvent",
            "VACCINATION": "END"
        }
    ]
}

  3. In a Command Prompt window, navigate to the Regression folder.

  4. Run the flatten_campaign.py script, providing the relative path to the overlay file and the path to and name of the new flattened campaign file that will be saved, using the arguments as shown below:

    python flatten_campaign.py --overlay experiment/campaign_overlay.json --saveto experiment/campaign.json

  5. Open the resulting campaign.json file and see that it has been flattened into a single file with nested JSON objects and any logical categories retained.

    {
    "Campaign_Name": "Vaccine",
    "Default_Campaign_Path": "defaults/generic-default-campaign.json",
    "Use_Defaults": 1,
    "Events":
    [
        {
            "VACCINATION": "BEGIN",
            "Event_Name": "SimpleVaccine",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 1,
            "class": "CampaignEvent",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.5,
                "Number_Repetitions": 3,
                "Target_Demographic": "Everyone",
                "Timesteps_Between_Repetitions": 7,
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "Cost_To_Consumer": 10,
                    "Waning_Config": {
                        "class": "WaningEffectMapLinear",
                        "Initial_Effect" : 1.0,
                        "Expire_At_Durability_Map_End" : 0,
                        "Durability_Map" : {
                            "Times"  : [   0,  30,  60,  90, 120 ],
                            "Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ]
                        }
                    },
                    "Vaccine_Take": 1,
                    "Vaccine_Type": "AcquisitionBlocking",
                    "class": "SimpleVaccine"
                }
            },
            "VACCINATION": "END"
        },
        {
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "Antigen": 0,
                    "Genome": 0,
                    "Outbreak_Source": "PrevalenceIncrease",
                    "class": "OutbreakIndividual"
                }
            }
        }
    ]
}

After the overlay files and default files are combined into a single campaign file, you can run a simulation using the EMOD executable (Eradication.exe).

Migration files

Migration files describe the rate of migration of individuals out of a geographic node. There are additional configuration parameters you can set to define the migration patterns and return time. There are four types of migration files that can be used by EMOD, namely, local migration, regional migration, air migration and sea migration files. The demographics file can be configured to exclude some nodes from certain types of travel.

Local migration describes foot travel into adjacent nodes. Regional migration describes migration that occurs on a road or rail network. Air migration describes migration that occurs by plane; you must indicate that a node has an airport for air migration from that node to occur. Sea migration describes migration that occurs by ship travel; you must indicate that a node has a seaport for sea migration from that node to occur. For both air and sea migration, it’s possible to originate in a node with an airport or seaport and migrate to a node without one, but the reverse is not true. Unlike the other migration files, the sea migration file only contains information for the nodes that are seaports.

To use the migration files, in the configuration file you must set Migration_Model to a valid migration type and indicate the path to the migration files you want to use. You must also set a parameter to enable each type of migration you want to include in the simulation. There are additional parameters in the configuration file you can use to scale or otherwise modify the data included in the migration files. The migration rate can be differentially set by age and/or gender. Additionally, a modifier can be applied for the migration rates to follow a distribution curve in the population. For more information, see Migration parameters.

Migration data is contained in a set of two files, a metadata file with header information and a binary data file. Both files are required. To create these files see, How to create migration files.

JSON metadata file

The metadata file is a JSON-formatted file that includes a metadata section and a node offsets section. The Metadata section contains a JSON object with parameters, some of which are strictly informational and some of which are used by Eradication.exe. However, the informational ones may still be important to understand the provenance and meaning of the data.

Parameters

The following parameters can be included in the migration metadata file:

Parameter

Data type

Description

AgesYears

array

An array that defines the age bins by which to separate the population and define migration rates.

Author

string

The author of the file.

DatavalueCount

integer

(Used by EMOD.) The number of outbound data values per node (max 100). The number must be the same across every node in the binary file. If you are using an older file that does not include this parameter, each migration type has the following maximum data values:

  • LOCAL_MIGRATION: 8

  • REGIONAL_MIGRATION: 30

  • AIR_MIGRATION: 60

  • SEA_MIGRATION: 5

DateCreated

string

The day the file was created.

GenderDataType

enum

Whether age data is provided for each gender separately or is the same for both. Accepted values are ONE_FOR_BOTH_GENDERS and ONE_FOR_EACH_GENDER.

IdReference

string

(Used by EMOD.) A unique, user-selected string that indicates the method used by EMOD for generating NodeID values in the input files. For more information, see Input files.

InterpolationType

enum

The method by which to interpolate the age-dependent rate data. Accepted values are LINEAR_INTERPOLATION and PIECEWISE_CONSTANT.

MigrationType

enum

The type of migration the data describes. Accepted values are:

  • LOCAL_MIGRATION

  • AIR_MIGRATION

  • REGIONAL_MIGRATION

  • SEA_MIGRATION

NodeCount

integer

(Used by EMOD.) The number of nodes to expect in this file.

NodeOffsets

string

(Used by EMOD.) A string that is NodeCount \(\times\) 16 characters long. For each node, the first 8 characters are the origin NodeID in hexadecimal. The second 8 characters are the byte offset in hex to the location in the binary file where the destination NodeIDs and migration rates appear.

Tool

string

The script used to create the file.
Example 
{
    "Metadata": {
        "Tool": "PythonApplication1.py", 
        "IdReference": "ABC", 
        "DateCreated": "Wed Dec  2 14:08:48 2015", 
        "InterpolationType": "PIECEWISE_CONSTANT", 
        "GenderDataType": "SAME_FOR_BOTH_GENDERS", 
        "NodeCount": 4, 
        "MigrationType": "LOCAL_MIGRATION", 
        "AgesYears": [
            14.99, 
            15, 
            45, 
            75, 
            105
        ], 
        "DatavalueCount": 3
    }, 
    "NodeOffsets": "000000010000000000000002000000240000000300000048000000040000006C"
}
Binary file

The binary file contains the migration rate data. Migration rate determines the average time until an individual takes a trip out of the node. This time is drawn from an exponential distribution with the parameter \(\lambda\) as the number of trips per day. Therefore, a migration rate of 0.1 can be viewed as 10 days until migration, on average. You can adjust this base rate using the Scalars and multipliers parameters.

The data in the binary file is laid out in a sequential stream of 4-byte integers that identify the origin and destination nodes followed by a stream of 8-byte floats that contain the migration rate for those node pairs laid out in the same order. Therefore, the length of the stream is defined by DatavalueCount. For each source node, there must be DatavalueCount \(\times\) (4 bytes + 8 bytes).

The following image shows how a binary file with a DatavalueCount value of 8 would be laid out.

_images/localMigrationBFF.jpg
How to create migration files

You can create the JSON metadata and binary migration files needed by EMOD to run simulations from either CSV or JSON data using Python scripts provided by IDM. You can assign the same probability of migration to each individual in a node (vector or human), or you can assign different migration rates based on age and/or gender (human only).

Note

The IdReference must match the value in the demographics file. Each node can be connected a maximum of 100 destination nodes.

For both scripts, use one of the following migration types:

  • LOCAL_MIGRATION

  • AIR_MIGRATION

  • REGIONAL_MIGRATION

  • SEA_MIGRATION

For regional migration, you may want to set up migration such that if a node is not part of the network, the migration of individuals to and from that node considers the closest road hub city. You can do this by constructing a Voronoi tiling based on road hubs, with each non-hub connected to the hub of its tile.

Create from CSV input

To use the same average migration rate for every individual in a node, create the migration files from a CSV input file.

  1. Create a CSV file with the following three columns (do not include column headers):

    From_Node_ID

    The origin node, which must match a node ID in the demographics file. You do not need to have the same number of entries for each From_Node_ID.

    To_Node_ID

    The destination node, which must match a node ID in the demographics file.

    Rate

    The average number of trips per day.

  2. Run the convert_txt_to_bin.py script using the command format below:

    python convert_txt_to_bin.py [input-migration-csv] [output-bin] [migration-type] [idreference]

This will create both the metadata and binary file needed by EMOD.

Create from JSON input

To vary the average migration rate based on age and/or gender, create the migration files from a JSON input file.

  1. Create a JSON file with the structure described in the sections below.

  2. Run the convert_json_to_bin.py script using the command format below:

    python convert_json_to_bin.py [input-json] [output-bin] [migration-type]

This will create both the metadata and binary file needed by EMOD.

JSON parameters

The following parameters are used in the JSON file for migration file generation.

Parameter

Data type

Description

IdReference

string

The metadata identifier used to generate the NodeID associated with each node in a simulation. The values for IdReference and NodeID must be the same across all input files used in a simulation.

Interpolation_Type

enum

The method by which to interpolate the age dependent rate data. Accepted values are LINEAR_INTERPOLATION and PIECEWISE_CONSTANT.

Gender_Data_Type

enum

Whether age data is provided for each gender separately or is the same for both. Accepted values are ONE_FOR_BOTH_GENDERS and ONE_FOR_EACH_GENDER.

Ages_Years

array

An array that defines the age bins by which to separate the population and define migration rates. The first value defines the upper bound of a bin starting at zero.

Node_Data

JSON object

The structure that contains the migration rate data for each node.

From_Node_ID

integer

The origin node for which to define migration rate.

Rate_Data

array

The structure that contains migration rate data for a single destination node.

To_Node_ID

integer

The destination node for which to define migration rate.

Avg_Num_Trips_Per_Day_Both

array

The array that lists the average number of trips per day for each age bin defined in AgesYears (male and female).

Avg_Num_Trips_Per_Day_Female

array

The array that lists the average number of trips per day for each female age bin defined in AgesYears.

Avg_Num_Trips_Per_Day_Male

array

The array that lists the average number of trips per day for each male age bin defined in AgesYears.
Example file 
{
    "IdReference": "ABC",
    "Interpolation_Type": "PIECEWISE_CONSTANT",
    "Gender_Data_Type": "ONE_FOR_EACH_GENDER",
    "Ages_Years": [14.99, 15, 45, 75, 105],
    "Node_Data": [{
        "From_Node_ID": 1,
        "Rate_Data": [{
            "To_Node_ID": 2,
            "Avg_Num_Trips_Per_Day_Male": [0.0, 0.1, 0.2, 0.3, 0.0],
            "Avg_Num_Trips_Per_Day_Female": [0.0, 0.3, 0.2, 0.1, 0.0]
        }]
    }, {
        "From_Node_ID": 2,
        "Rate_Data": [{
            "To_Node_ID": 1,
            "Avg_Num_Trips_Per_Day_Male": [0.0, 0.2, 0.5, 0.3, 0.0],
            "Avg_Num_Trips_Per_Day_Female": [0.0, 0.5, 0.3, 0.2, 0.0]
        }]
    }]
}
Climate files

There are two general types of climate files usable by EMOD, namely, climate files generated through actual data, referred to as “climate by data,” and climate files generated from the Koppen classification system, referred to as “climate by Koppen.” Climate data (both types) is contained in a set of two files, a metadata file with header information (<name>.bin.json) and a binary data file (<name>.bin).

The metadata file is a JSON-formatted file that includes a metadata section and a node offsets section. The Metadata parameter contains a JSON object with parameters, some of which are strictly informational and some of which are used by Eradication.exe. However, the informational ones may still be important to understand the provenance and meaning of the data.

In a second section, the NodeOffsets parameter contains a list of hex-encoded 16-byte values used to find the data for each given node (the NodeID).They are not 16-byte offsets, but instead, two 8-byte hex-encoded character strings. This encoding includes the source NodeID. You can map the binary data to its corresponding source NodeID by using the NodeOffset information.

The binary file contains the climate data in a sequential stream. In other words, it presents all the data for the first node, then all the data for the second node, all the way through to the last node.

To use the climate files, you must set Climate_Model to either “CLIMATE_BY_DATA” or “CLIMATE_BY_KOPPEN”, as appropriate, in the configuration file. There are also additional parameters in the configuration file you can use to scale or otherwise modify the data included in the climate files.

Climate by data

Climate by data files contain real data gathered from weather stations in the region to be simulated. This includes rainfall, temperature, relative humidity, and so on. At this time, the EMOD executable (Eradication.exe) reads land temperature data, but does not use the data in any calculations. IDM clones the air temperature and uses that as the land temperature in the climate data files. If you are going to be constructing your own climate files, we advise you to do the same.

Metadata file

The following parameters in the metadata section are informational:

Parameter

Data type

Description

DateCreated

string

The day the file was created.

Author

string

The author of the file.

OriginalDataYears

string

The years from which the original data was derived.

StartDayOfYear

string

The day of the year representing the first day in the climate file.

DataProvenance

string

The source of the data.

The following parameters in the metadata section are used by Eradication.exe:

Parameter

Data type

Description

IdReference

string

A unique, user-selected string that indicates the method used for generating NodeID values in the input file. For more information, see Input files.

NodeCount

integer

The number of nodes to expect in this file.

DatavalueCount

integer

The number of data values per node. The number must be the same across every node in the binary file.

UpdateResolution

enum

The time resolution of the climate file. Available values are:

  • CLIMATE_UPDATE_YEAR

  • CLIMATE_UPDATE_MONTH

  • CLIMATE_UPDATE_WEEK

  • CLIMATE_UPDATE_DAY

  • CLIMATE_UPDATE_HOUR

An example of climate by data metadata is as follows:

{
    "Metadata": {
        "DateCreated": "Sun Sep 25 19:02:09 2011",
        "Tool": "createclimateheader.py",
        "Author": "authorName",
        "IdReference": "Gridded world grump2.5arcmin",
        "NodeCount": 1,
        "DatavalueCount": 3650,
        "UpdateResolution": "CLIMATE_UPDATE_DAY",
        "OriginalDataYears": "1990-1993",
        "StartDayOfYear": "January 1",
        "DataProvenance": "47 consecutive months of data were used to generate one average year of data that is repeated for 10 years"
    },
    "NodeOffsets": "144B07A400000000"
}
Binary file

The binary file is a stream of 4-byte floating point values that contain the data value at the data count position for a given node, running from 1 to the maximum data count value.

The binary format is as follows:

_images/climate-by-data-binary.jpg
Climate by Koppen

The Koppen classification system is one of the most widely used climate classification systems. The Koppen classification system makes the assumption that native vegetation is the best expression of climate.

Metadata file

The following parameters in the metadata section are informational:

Parameter

Data type

Description

DateCreated

string

The day the file was created.

Author

string

The author of the file.

DataProvenance

string

The source of the data.

Tool

string

The script used to create the file.

The following parameters in the metadata section are used by Eradication.exe:

Parameter

Data type

Description

IdReference

string

A unique, user-selected string that indicates the method used for generating NodeID values in the input file. For more information, see Input files.

NodeCount

integer

The number of nodes to expect in this file.

An example of climate by Koppen metadata is as follows:

{
    "Metadata": {
        "DateCreated": "Sun Sep 25 19:08:52 2011",
        "Tool": "createclimateheader.py",
        "Author": "authorName",
        "IdReference": "Gridded world grump2.5arcmin",
        "NodeCount": 2,
        "DataProvenance": "Köppen-Geiger Classification System from http://koeppen-geiger.vu-wien.ac.at/"
    },
    "NodeOffsets": "157D075200000000157E07520000000"
}
Binary file

The binary file parameters use the naming convention below to store the data.

Parameter

Data type

Description

KoppenIndexX

integer, 4 bytes

The Koppen Index value, with X running from 1 to the maximum number of nodes.

The binary format is as follows:

_images/climate-by-koppen-binary.jpg
Load-balancing files

If you are running a large simulation with multiple nodes, you may want to use a load balancing file to distribute the computing load among multiple cores. This can be especially helpful if the nodes vary considerably in size and, therefore, processing time. If no load balancing file is submitted, the Eradication.exe allocates simulation nodes to cores according to a checkerboard pattern.

For each simulation, the load balancing file contains information about the relative level of processing time required for each geographical node. The Eradication.exe can then allocate nodes to processors in such a way that the total processing required is evenly distributed across all processors.

To use a load balancing file, you must set the configuration parameter Load_Balance_Filename to the path to the load balancing file, relative to the input file directory. Load-balancing files can be JSON (JavaScript Object Notation) files, which are preferred, or binary files.

JSON file

A JSON load-balancing file contains the Load_Balance_Scheme_Nodes_On_Core_Matrix parameter, assigned an array of arrays, each of which represents a core and lists the NodeID of each node to be processed on that core. If any node contained in the demographics file is not listed in the load-balancing file, it will be processed on the first core.

For example, the load-balancing file shown below distributes the processing for 100 nodes across 4 cores, assigning more nodes to particular cores when those nodes require less processing time.

{
    "Load_Balance_Scheme_Nodes_On_Core_Matrix": [
        [1, 2, 3, 4, 5, 11, 12, 13, 14, 15, 21, 22, 23, 24, 25, 31, 32, 33, 34, 35, 45],
        [6, 7, 8, 9, 10, 16, 17, 18, 19, 20, 26, 27, 28, 29, 30, 36, 37, 38, 39, 40, 46, 47, 48, 49, 50, 56, 57, 58, 59, 60, 67, 68, 69, 70],
        [61, 62, 63, 64, 65, 66, 71, 72, 73, 74, 75, 76, 77, 81, 82, 83, 84, 85, 86, 87, 91, 92, 93, 94, 95, 96, 97],
        [41, 42, 43, 44, 51, 52, 53, 54, 55, 78, 79, 80, 88, 89, 90, 98, 99, 100]
    ]
}
Binary file

A binary load-balancing file starts with an initial unsigned 4-byte integer that indicates the number of nodes. Following that value is a series of 4-byte unsigned integers representing the NodeID values. The number of values will be equal to the previously read number of nodes. Following that, another series of 4-byte floating point values, with each value representing the relative processing time required for each geographic node. Again, the number of values will be equal to the previously read number of nodes. The series of values are set up such that the \(i^{th}\) entry in the series is equal to the cumulative proportion of the processing load for all the previous nodes 0 through \(i\).

The cumulative nature of each node’s value does not mean each node is assigned that amount for its processing load. Rather, it is a way to make the internal calculations more efficient. For example, if you had ten nodes and each node was assigned 10% of the load, the values assigned from node0 to node9 would be the following: 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9 and 1.0.

The following diagram shows the format for the binary load-balancing file data:

_images/loadbalancingBFF.jpg
Serialized population file

To model a population with endemic disease, you cannot use a common modeling technique in which you introduce a disease outbreak to a naive population and analyze the immediate aftermath. Doing so would create a population missing the levels of natural immunity built up in the population due to the history of exposure to the pathogen. Instead, you must run the simulation for a period of time until the disease dynamics reach an equilibrium (aside from stochastic noise). This is known as steady state. The simulation output prior to that point is disregarded. This is a modeling concept known as simulation burn-in, borrowed from the electronics industry where the first items produced by a manufacturing process are discarded before the process is applied.

However, the time necessary to run simulations until this point can be significant, especially for large populations. Indeed, for endemic disease present at low absolute prevalence, you should simulate a larger population size that allows a small number of infected individuals to be represented.

EMOD avoids the need to run the burn-in period again and again with each simulation by using serialization to save the population state after it reaches equilibrium. Then, when you want to begin a subsequent simulation investigating the outcome of a particular set of interventions, you can begin the simulation at that point rather than needing to re-run the burn-in period. You can serialize the population at multiple time steps during a simulation.

The serialized population files created are placed in the output directory and use the naming convention state-<timestep>.dtk. They are binary files that contain state information about every agent in a simulation: their health status, age, property values, and more. These files can be consumed by subsequent simulations to decrease run time.

Note

If you used repeating interventions during the burn-in period, those interventions will not continue based on the information in the serialized population file. Check your campaign file for repeating interventions and reconfigure them as needed for the period after burn-in.

See Simulation setup parameters for more information on configuration. See Serializing populations for more information on utilizing serialized populations in your simulations.

File format

Serialized population files are saved in JSON format. The file structure reflects the hierarchical structure of the objects in Eradication.exe. Each file starts with a header and then contains information about the simulation and the nodes. The following figure gives a rough overview of the JSON file structure (note that only vector or malaria simulations will have larval habitats, vector populations, or vector life cycles).

_images/serialized_file_format.png
Internal state

The structure of a serialized population file reflects the relations of objects in a simulation. On the highest level, a serialized population file contains a list with nodes, each node is the root of a tree. At the configured timestep the simulation calls Node::serialize() which then calls the serialized method of other members of this object. The Node class, for instance, contains a list with individuals, each individual has certain attributes and a list of infections. Each infection has certain attributes and might contain again a list of objects, etc. This continues until there are no more objects.

All objects that are instantiated from classes that inherit from ISerializable and implement the ISerializable interface can write itself to a buffer. It depends on the chosen writer how this buffer is written and where it is written. Here we assume that a JSON writer is used and that the writer adds variable names and formatting characters so that a valid JSON file is generated. A similar mechanism is at play when a simulation is loaded again from a file. The names of variables and their values are used to re-instantiate the same objects. Mind that EMOD is written in a compiled language, so the description of data and objects (classes and variable types) in the source code must match the data types in the serialized population file, e.g. if a variable is of type integer changing its value to a float won’t have the anticipated effect.

Multi-core

If the simulation is run on several cores, each core saves one file at the configured timestep(s). To continue the simulation one EMOD file must be defined per node.

File Name

The format for single core is: state-timestep.dtk e.g. state-00100.dtk

The format for multi-core is: state-timestep-core.dtk e.g. state-00100-001.dtk

Running a simulation

The EMOD executable (Eradication.exe) consumes the input files, configuration file, and, optionally, campaign file to run simulations that model disease dynamics and campaign efficacy. The simulation type controls the transmission mechanism of the disease. Each agent, whether human or vector, is simulated and follows a set of rules that govern their health and behavior.

You have a few different options for running simulations. The option you choose will depend upon whether you want to run one or more simulations, to run simulations locally or on a remote cluster (for large simulations or multiple simulations), or to run simulations for debugging the source code. This topic briefly describes the different options you have for running simulations. Because the model is stochastic, you must run simulations multiple times to produce scientifically valid results.

Run a single simulation

It is simplest to run a single simulation using the EMOD command-line options. This will run a single simulation and put the output files in a local directory.

You must either download the latest version of Eradication.exe from GitHub or clone the EMOD source from GitHub and build Eradication.exe yourself. This gives you access to the latest features and parameters for EMOD. To learn EMOD, you can also download the EMOD scenarios, which contains all input files needed to run local simulations that model a variety of disease scenarios.

Run multiple simulations

Because the EMOD model is stochastic, simulations must be run multiple times to return scientifically valid results. Therefore, you have the following options to run multiple simulations at a time, either locally or remotely on a high-performance computing (HPC) cluster. Generally, only small simulations should be run locally.

Many of these options are scripting languages that you can also use to modify the files consumed by EMOD, simplifying your workflow when running many simulations.

Run simulations for debugging

If you are helping advance the EMOD model by contributing to source code, there are other options for running simulations that provide debugging support. These options for running simulations are not recommended if you are not modifying the source code.

You can run a simulation locally from Visual Studio using the built-in debugger. You will be able to put in breakpoints and step through the code while inspecting the values of different state variables throughout the simulation.

You can use regression_test.py in the GitHub Regression directory to run multiple simulations on a cluster, including running the suite of regression tests run by the IDM testing team. For more information, see Regression testing.

Directory structure

Although there are many ways you can structure the files needed to run a simulation, we recommend the following to keep your files organized and simplify the file paths set in the configuration file or passed as arguments to Eradication.exe.

  • Place the configuration and campaign files needed for a simulation in the same directory. This is also known as the working directory.

    However, if you are using overlay files, you may want the default configuration or campaign file in a separate directory so they can be used with different overlay files for other simulations.

  • Place all demographics and climate files for a given region in the same directory.

  • Place output for a simulation in a subdirectory of the directory containing configuration and campaign files.

It is not important where you install Eradication.exe or the Eradication binary for Linux.

Run a simulation using the command line

Using command-line options is the simplest way to run an EMOD simulation. This topic describes the commands available for running simulations.

The EMOD executable (Eradication.exe) and Eradication binary for Linux also provide commands that provide information about the version of EMOD that is installed, such as available parameters and simulation types. For more information, see Generate a list of all available parameters (a schema). The examples below show the Windows Eradication.exe, but the options are the same for the Eradication binary for Linux on CentOS.

Command options

The following command-line options are available for running EMOD simulations. Paths can be absolute or relative to the directory you are in when running the commands, unless otherwise specified.

Simulation options

Long form

Short form

Description

--version

-v

Get version information.

--schema-path

Path to write the schema (the complete list of all parameters and associated information). If not specified, the schema will be written to stdout.

--config

-C

Path to the configuration file. If not specified, EMOD will look for a file named config.json in the current directory.

--input-path

-I

Path to the directory containing other input files (except the campaign file, which must be in the current directory). If not specified, EMOD will look for files in the current directory. The specific demographics, climate, etc. files to use must be listed in the configuration file.

--output-path

-O

Path to the directory where output files will be written. If not specified, EMOD will create an “output” directory and overwrite any previous output in that directory.

--dll-path

-D

Path to the EMODule root directory. For more information, see Custom reporters.

--python-script-path

-P

The path to Python scripts to use for pre- or post-processing.

The following options are for monitoring the progress of simulations running on an high-performance computing (HPC) cluster. They are optional for any simulation, but they must be used together. To monitor progress, listen for User Datagram Protocol (UDP) messages on the specified host and port.

HPC cluster options

Long form

Description

--monitor_host

The IP address of the commissioning/monitoring host. Set to “none” for no IP address.

--monitor_port

The port of the commissioning/monitoring host. Set to “0” for no port.

--sim_id

The unique ID for this simulation. This ID is needed for self-identification to the UDP host. Set to “none” for no simulation ID.

--progress

Send updates on the progress of the simulation to the HPC job scheduler.
Usage

  1. Open a Command Prompt window and navigate to the working directory, which contains the configuration and campaign files.

  2. Enter a command like the one illustrated below, substituting the appropriate paths and file names for your simulation:

    ../Eradication.exe -C config.json -I C:\EMOD\InputFiles -O Sim1Output

    If you do not specify anything when invoking Eradication.exe, it will not execute with all defaults, but will instead tell you how to invoke the --help command.

  3. EMOD will display logging information, including an errors that occur, while running the simulation. See Error and logging files for more information.

  4. Output files will be placed in the directory specified. For more information on how to evaluate and analyze the output, see Output files (reports).

Run a simulation using mpiexec

The application mpiexec is used to run multi-node simulations in parallel. Eradication.exe is “single threaded”, so it uses only one core for processing. If you run a simulation with multiple geographic nodes using mpiexec instead of invoking Eradication.exe directly, multiple copies of Eradication.exe will be running, with one copy per core processing data for a single node at a time. Message Passing Interface (MPI) communicates between the cores when handling the migration of individuals from one node to another.

Although mpiexec can be used to run a simulation in parallel on your local computer, it is more often used to run complex simulations in parallel on an HPC cluster or several linked computers. Mpiexec is part of the Microsoft HPC Pack 2019 SDK (64-bit) installed as a prerequisite for building Eradication.exe from the EMOD source code. See EMOD source code installation for more information.

Note

If you get an error that the mpiexec command cannot be found, you must add the path to mpiexec to the PATH environment variable. For example, open Control Panel and add the path C:\Program Files\Microsoft HPC Pack 2012\Bin to PATH.

Usage

  1. Take note of the number of cores on your computer or cluster.

    If running locally, we recommend running mpiexec with one fewer cores than are available, so one core is reserved for the operating system. The simulation can be run on all available cores and will complete faster, but the desktop will not be responsive.

  2. Open a Command Prompt window and navigate to the directory that contains the configuration and campaign files for the simulation.

  3. Invoke Eradication.exe using mpiexec as follows, replacing the number of cores, paths, and command options as necessary for your environment. See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.

    mpiexec -n 3 ..\Eradication.exe --config config.json --input-path ..\InputDirectory\Garki --output-path OutputGarki

Mpiexec will start multiple copies of Eradication.exe as specified by -n. Those instances will communicate with each other via MPI. If all cores are on a single computational node or host, they will use internal networking to carry the MPI packets.

You can also link together several computers with MPI using the mpiexec -host option. For example, if you were using six cores on two computers, you could run three copies of Eradication.exe on the first computer, and three more could be run on the second computer. Again, this assumes that each computer has at least three cores.

For more information about mpiexec, see MSDN.

Run a simulation using Python

If you used Python to create or modify JSON files as shown in Example scripts to modify a configuration file, it may be convenient to invoke Eradication.exe to run a simulation from a Python script. One way of doing this is shown below using the subprocess package.

import subprocess

# specify paths
binary_path = "binDirectory\Eradication.exe"
input_path = "inputDirectory\Namawala\

# commission job
subprocess.call( [binary_path, "-C", "config.json", "--input", input_path] )

See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.

Run a simulation using MATLAB

If you used MATLAB to create or modify JSON files as shown in Example scripts to modify a configuration file, it may be convenient to invoke Eradication.exe to run a simulation from a MATLAB script. One way of doing this is shown below using the dos command.

exe_name = fullfile( binDirectory, 'Eradication.exe' );
exe_args = [ '-C config.json -I ', fullfile( inputDirectory, 'Namawala' ) ];
[status,result] = dos( ['cd ', WorkDirectory, ' && ', exe_name, ' ', exe_args ], '-echo' );

See Run a simulation using the command line for more information about the command options available for use with Eradication.exe.

Speed up EMOD simulations

While small simulations can be run quickly on a local computer, the time and memory needed to complete a simulation can grow significantly when simulations become larger and more complex. For example, a single geographical node simulation might use 3 GB with one core in order to run successfully in one minute or less, while another simulation job may require 32 GB in a dual-core system in order to complete in approximately the same amount of time.

As your simulations grow, you will likely want to run simulations on an HPC cluster or take other steps to improve performance and reduce processing time. This topic describes many of the steps you can take to speed up EMOD simulations.

Parallel processing

The EMOD executable (Eradication.exe) is “single threaded”, meaning that for processing, it will use only one core. However, you can use the Message Passing Interface (MPI) to run multiple copies of Eradication.exe in parallel, either locally or on an HPC cluster. To run a simulation in parallel, you must invoke Eradication.exe with the mpiexec command. For more information, see Run a simulation using mpiexec.

Parameter settings

You can also set various parameters in the configuration file that will improve performance by scaling down the amount of data used or optimizing data processing. See the parameters listed in the sections below for guidance on making performance adjustments. See Configuration parameters for more information about each of the parameters.

Scaling and sampling
Simulation_Duration

Obviously, simulating a shorter timespan will take less processing time. However, the processing time is often driven by the number of infections or immune updates, so running a simulation after all infections have cleared may not increase processing time much. For more information, see Simulation setup parameters.

Individual_Sampling_Type

Instead of the default Individual_Sampling_Type setting of “TRACK_ALL”, you can speed up performance by sampling such that each individual object represents more than one person. For example, a simulation with a population of 1 million and sample rate of 0.1 would simulate 100,000 individuals, with each given a weight of 10. Sampling can be fixed at a particular rate or can adapt the rate based on certain criteria, such as age or immune state. However, you should be especially careful not to undersample simulations to the point where they are overly sensitive to rare stochastic events. For more information, see Sampling parameters.

Population_Scale_Type and x_Base_Population

Alternatively, you can simply reduce the total population of the simulation using Population_Scale_Type set to “FIXED_SCALING” and x_Base_Population set to less than one. For more information, see Scalars and multipliers parameters.

Processing
Num_Cores

For large, spatially distributed simulations, running the intra-node dynamics (for example, infection and immune dynamics) in parallel on multiple cores may be very advantageous. Ideally, the timing would be reduced inversely to the number of cores. However, there are costs to serializing individuals for migration over MPI, as well as considerations for balancing the CPU load on each core. These issues may be mitigated using a load balancing input file that is suitable to the geography being simulated. See Load-balancing files for more information.

Serializing populations

Some simulations can take a long time to run and the part you are really interested in analyzing isn’t until closer to the end. You’d like to save the state of the simulation just before the interesting stuff and then restart from that spot. This would allow you to iterate more quickly on different intervention strategies or just trying to understand what the simulation is doing better. EMOD supports this ability with a feature called “serialized populations.”

Serializing is the idea of saving the state of object so that there is enough information to recreate that object later. Deserializing is the reverse, where you create a new object but initialize it with the state that was saved. For more information, see serialization. This is analogous to the sleep feature in your computer: when you put it to sleep, it serializes data of the objects running the system; when you start it back up again, it recreates what was running from that saved state.

The serialized population feature in EMOD allows you to save the state of the people and restart from that saved state. This state includes the person’s health, infections, any interventions that they have, and more. This is especially useful when you need to create a population that has natural immunity to a pathogen (i.e. the pathogen is not novel and the population is not naive.) It is important to note that only events that have already occurred will be saved in the serialized population; for example, if the person has received only the first dose of a two dose vaccine when the simulation was serialized, the person will only have that one dose when the simulation is deserialized. The logic to give the person the second dose will still need to be added to the simulation.

Being able to serialize the population is a powerful feature and can save the researcher lots of time. However, it does have it is idiosyncrasies. The following information is intended to help the user understand how serialization works, how to write a file, how to read from a serialized file, and what parameters you can change when reading from a serialized file. For more information on the format of serialized files, see Serialized population file.

Example use cases

Serialization is useful for a variety of use-cases; we have outlined some common examples below.

Try out different interventions (Simple burn-in)

To create a population with an endemic disease, one option is to start with a naïve population and run simulation till disease dynamics reach an equilibrium. These simulation burn-in methods can take several years of simulation time until a steady state is reached. Saving the state to a file and continuing from this state reduces the time needed to model the effect of different interventions.

Burn-in is especially effective when exposure and individual immunity is age structured within the population. For example, if older individuals have higher antibody levels than younger individuals, due to prolonged exposure.

Ultimate Report

In case existing reports don’t have what you need, a serialized population file contains all the internal states of the people in the population. By saving serialized population files periodically and then extracting the data from these files, it is possible to gain very deep insights into the simulation. The extracted “report data” can then be processed with dtk_post_process or analyzers such that you only save the extracted data. The serialized population files can be very big so you could use this mechanism extract the data you want and then delete the large files.

Reconfigure (currently only larval habitats)

When a simulation is saved to file and then loaded again, the state is exactly the same as it was at the moment it was saved. There are options to reconfigure the simulation and read parameters from config.json instead of the serialized file. This is called “masking” and is controlled by the parameters Serialization_Mask_Node_Write and Serialization_Mask_Node_Read. These options are currently very limited and only work for larval habitats.

Create a synthetic population

Sometimes you want to create a large spatial scenario but you don’t want to wait to do burn-in just to get a population with reasonable immune systems. One way you could solve this problem is to run a smaller one-node scenario that has a prevalence similar to the overall area you are trying to model. You do a burn-in with this smaller scenario to generate a representative population and serialize that population at the end. You could then use the people in this representative scenario to generate a larger scenario and larger serialized file.

The state of all the individuals in a simulation is saved in a serialized population file. Python libraries exist to manipulate the file and can be used to create, remove, or change attributes of an individual.

Calibration Chaining

You can calibrate for a first period of time and then save the file. From that starting point, you can calibrate for the next period of time and so on.

Serialized population file

The information below describes how serialized files work. For more information on formatting serialized files, see Serialized population file.

Internal state

A serialized population file contains the internal state of the objects used to create the population in that realization. This internal state includes lots of implementation details that are not really meant for user consumption. With the right tools, you can open a file and look at its contents. The core of the information is in JSON format. For more detailed information, see Serialized population file.

These implementation details are frequently the things that cause the data in the file to change. When adding a new feature or fixing a bug, the developer might need to add new state to an object that needs to be maintained from timestep to timestep. This new state could be related to a new model or something that just makes the model run faster. Either way, this new information needs to be written to and read from the file. Hence, if you are updating from an older version to a newer one, you will likely need to regenerate your serialized files.

Population

The file contains the state of a human population and, for vector or malaria simulations, a vector population. All the nodes that belong to the simulation and the individuals that belong to a node are saved. Furthermore, each individual has an internal state and certain characteristics that belong to it, like infections, drugs or interventions. Thus, interventions that were distributed before the population was saved are still active. Node-level interventions or event coordinators are not saved because they are not part of the population: they can change they state of a population but are not part of it.

Similar to individuals, vectors and their habitats are saved.

Multi-core

Serializing a simulation also works on a multi-core system: one file per core is written. To continue the simulation all the created files must be defined in config.json and must use the same number of cores.

Upgrading to new executable

There is a strong dependency between the program code and the serialized file. Changing the EMOD executable or modifying source code (especially removing, renaming or adding variables) will require a rerun of the burn-in.

File sizes

Serialized population files can be quite large - sometimes on the order of gigabytes. This is mostly impacted by the size of your population (and for vector or malaria simulations, the size of the vector population). Since the file already makes use of compression, compressing a serialized file will provide minimal benefit.

The size of the file can become a memory issue when reading from the serialized file. Reading large files, for example over 5 gigabytes, requires a lot of memory to both read the file and create the objects from that file. The amount of RAM you have available for each of your simulations should factor into how large of a file you want to use. If this is a concern, one can set the parameter logLevel_Memory to DEBUG when running the simulation to serialize. This will tell you how much memory will be needed for the simulation after you read it back in. However, it does not include the memory needed to read the file. If you are allowed 8-GB of memory per core, your simulation is using 7-GB, and your file is 2-GB, you could be in danger of using more memory than you are allowed.

Creating and editing serialized populations
Saving

To create and save serialized population files, configure the following parameters and then run a simulation. The output serialized population file is a binary file that is saved with a name similar to state-[timestamp].dtk, where [timestamp] is number of timesteps in the data file (e.g. state-00100.dkt). Note that the size of the population impacts the size of the file, so working with smaller populations will create smaller serialized files.

Config parameters

The following configuration parameters must be set to create serialized files:

Parameter

Data type

Default

Description

Serialized_Population_Writing_Type

enum

NONE

The type of serialization to perform. NONE for no serialization; TIME to use the definition from Serialization_Times; and TIMESTEP to use definition from Serialization_Time_Steps.

Serialization_Times

array of floats

[]

The list of times at which to save the serialized state to file. 0 indicates the initial state before simulation, ‘n’ indicates the time to serialize in terms of start time and step size, rounded up to the nearest timestep. Time is in term of days.

Serialization_Time_Steps

array of integers

[]

The list of timesteps after which to save the serialized state to file. 0 indicates the initial state before simulation, n indicates after the nth timestep.

Serialization_Mask_Node_Write

integer

0

A bitmask that defines what is NOT written to the file. O implies write everything to the file, 16 implies do NOT write larval habitats to the file.

Serialization_Precision

enum

REDUCED

REDUCED is used to reduce the size of the serialized file. FULL give more floating point precision but creates larger files. FULL precision is needed if you want the continuing simulation to be exactly the same as if you didn’t start from a serialized file.
Example JSON

The following example will save the population on day 50 and day 100.

{
    "Serialized_Population_Reading_Type": "NONE",
    "Serialized_Population_Writing_Type": "TIME",
    "Serialization_Times": [
        50,
        100
    ],
    "Serialization_Mask_Node_Write": 0,
    "Serialization_Precision": "REDUCED"
}
Starting from

You include and use serialized population files in a simulation by configuring the following parameters. If you do not specify an accurate path and filename, EMOD generates an error.

Config parameters

The following configuration parameters must be set to create serialized files:

Parameter

Data type

Default

Description

Serialized_Population_Reading_Type

enum

NONE

Set to READ to enable reading from a serialized population file, set to NONE otherwise.

Serialized_Population_Path

string

empty string

The root path for the serialized population files.

Serialized_Population_Filenames

array of strings

[]

An array of filenames with serialized population data. The number of filenames must match the number of cores used for the simulation. The path to the files is defined in Serialized_Population_path.

Serialization_Mask_Node_Read

integer

0

This is a bitmask to control what data is loaded. 0 implies loading all of the data in the serialized file. 16 implies that we do not load the larval habitat data from the serialized file and use the parameters in the configuration file instead.

Enable_Random_Generator_From_Serialized_Population

boolean

0

Determines if the random number generator should be extracted from a serialized population file. Enabling this (set to 1) starts a simulation from this file with the exact same random number stream and location in that stream as when the file was serialized.
Example JSON

In this example a population is loaded from file ./my_files/state-00050.dtk. Everything saved in the file is read (“Serialization_Mask_Node_Read”: 0).

{
    "Serialized_Population_Writing_Type": "NONE",
    "Serialized_Population_Reading_Type": "READ",
    "Serialized_Population_Path": ".",
    "Serialized_Population_Filenames": [
        "state-00050.dtk"
    ],
    "Serialization_Mask_Node_Read": 0
}
Manipulating

IDM provides a Python package EMOD-Py with installation instructions and documentation to manipulate a serialized population file.

The following provides a list of a few scripts that are available in EMOD-Py. Please see the package for others and more details.

Remove all genomes - When using Full Parasite Genetics, this script will remove all of the genomes from the existing infections. This can be helpful when you want to replace existing genomes with new ones.

Remove all infections - Sometimes you want people to have developed immunity but want to control who is infected when the simulation starts. This script allows you to remove all the infections from the humans (and vectors) so that you can determine who gets infected and when.

Remove all interventions - Like removing infections, you might just want a certain demographic of people and their immunities but you want to determine what interventions they have.

Add/remove an individual property - Sometimes you need to add a new IP to the population in order to implement a new intervention strategy. If so, it is better to use a script and add the new IP to the population. This will ensure things work like you expect.

Modify vector habitat - You might have situation where there is a change in the environment like a period of drought or extra long rainy season. If so, you might want the ability to change the habitat to reflect this environmental change.

Changing parameters

When you are reading from a serialized file, you have a contention between what is in the serialized file and what is in the input files. Currently, there is not a good way to know what parameters you can change and which ones you cannot. This section is intended to provide some high level guidance.

Changing serialized configuration parameters

Not every parameter can be changed after the creation of serialized files. The following overview is intended as high-level guidance for what changes can and cannot be made.

Simulation parameters
Cannot be changed

  • Simulation_Type The type of simulation determines the parameters and the types of objects in the file.

  • Enable_Demographics_Builtin

  • Default_Geography_Initial_Node_Population

  • Default_Geography_Torus_Size

  • Node_Grid_Size This is not serialized; the value is loaded from the configuration file every time a simulation is created.

  • Enable_Interventions

  • Campaign_Filename

  • Load_Balance_Filename You must use the same number of cores that you used when you created the serialized file. The nodes will be on the those same cores.

  • Malaria_Model

Can be changed

  • Simulation_Duration This controls the number of days the simulation will run from the day it starts (when the executable begins executing).

  • Start_Time It can be useful to set this parameter to the day that the file was serialized plus one timestep. For example, if you serialized the file on day 100 and your timestep was 5, setting Start_Time = 105 will make the appearance that the simulation started right where it left off. It is also fine to have it start at 0.

  • Custom_Individual_Events You can easily add new events but must be careful when removing them. If an individual has a serialized intervention that emits the event that you delete, you should get an error de-serializing the file because the event is unknown.

  • Malaria_Drug_Params These parameters are not serialized so they can be changed. However, there are a few caveats:

    # If you have handed out drugs to people and the people have the drugs in them when you serialize, then you must have drugs in Malaria_Drug_Params with the same name. When the people are de-serialized, the drug intervention will look for the drug parameters with the same name as when the person was serialized. # A person who had drugs when serialized will still be in that state when de-serialized. The previous values created the person’s current state; changing the parameters will not reverse the previous effects. # Given the person’s state when serialized, the new parameters could cause weird effects depending on how the parameters are changed. For example, if you shorten a delay significantly, the drug could suddenly have no remaining effect.

  • Serialized_Population_Reading_Type

  • Serialized_Population_Writing_Type

  • Serialized_Population_Path

  • Serialized_Population_Filenames

  • Enable_Random_Generator_From_Serialized_Population

Individual parameters
Can be changed

  • Enable_Aging This parameters is not serialized and can be changed. However, if it was enabled and you disable it, people will be frozen at whatever age they were during serialization. Conversely, people will start aging when you enable it. This could mean everyone is the same age.

  • Infection_Updates_Per_Timestep This parameter is not serialized and can be changed. However, it could impact some interventions like drugs.

  • Enable_Superinfection

  • Max_Individual_Infections

  • Age_Dependent_Biting_Risk_Type

  • Newborn_Biting_Risk_Multiplier

Infection parameters
Can be changed

  • Incubation_Period_Distribution This parameter is not serialized and can be changed, including the extra parameters used in defining the distribution.

  • Infectious_Period_Distribution This parameter is not serialized and can be changed, including the extra parameters used in defining the distribution. (Note this parameter is not used in malaria simulations.)

  • Base_Infectivity This parameter is not serialized and can be changed, including the extra parameters used in defining the distribution. (Note this parameter is not used in malaria simulations.)

  • Malaria_Strain_Model This parameter is not serialized and can be changed but it will only impact new infections.

Changing serialized campaign parameters

Campaigns are used to distribute interventions to the people in the scenario. When it comes to serialization, only the interventions that have already been distributed to people are serialized. For example, if you are distributing drugs to people when they exhibit clinical symptoms, then people who exhibited symptoms before the file was serialized should have their drugs. However, to get drugs to the people exhibiting symptoms after reading from the serialized file, you will need to add the campaign events that do that distribution.

The following overview is intended as high-level guidance for what changes can and cannot be made.

Campaign events & event coordinators

See Events and event coordinators for more information on events and event coordinators.

Events

Campaign events are not serialized.

Event coordinators

Event coordinators are not serialized. Any coordinator that was periodically distributing interventions will need to be added to the new campaign.

Interventions
Node-level interventions

Node-level interventions are not serialized. Any node-level vector control will need to be redistributed. Any NodelLevelHealthTriggeredIV that is responding to events will also need to be redistributed.

Individual-level interventions

Some may be serialized. If the intervention has been distributed to the person, then it will be serialized. For example, if the person received a bednet before the file was serialized, then the serialized person will still have that bednet with however much its performance has decayed. However, if the person is supposed to receive drugs if they become clinical and the person has not been clinical yet, then you need to include that drug logic in your new campaign.

Changing serialized demographics parameters

Not every parameter can be changed after the creation of serialized files. The following overview is intended as high-level guidance for what changes can and cannot be made.

Population-level parameters
Cannot be changed

  • Age_Initialization_Distribution_Type

  • Birth_Rate_Boxcar_Forcing

  • Birth_Rate_Dependence

  • Birth_Rate_Time_Dependence

  • Birth_Rate_Sinusoidal

  • Death_Rate_Dependence

  • Enable_Birth

  • Enable_Demographics_Birth

  • Enable_Demographics_Risk

  • Enable_Initial_Prevalence

  • Enable_Natural_Mortality

  • Enable_Vital_Dynamics

  • Population_Scale_Type

  • x_Base_Population

  • x_Birth

  • x_Other_Mortality

Can be changed

  • Enable_Disease_Mortality

NodeAttributes
Cannot be changed

  • InitialPopulation

  • InitialVectorsPerSpecies

  • LarvalHabitatMultiplier This is read but not used. Both the LarvalHabitatMultiplier and the x_Temporary_Larval_Habitat are applied when a habitat is created at the beginning of a simulation. When the habitat is serialized, it is stored with the results of these multipliers. If you are reading from a serialized file and Serialization_Mask_Node_Read = 0, then you ignore both LarvalHabitatMultiplier and x_Temporary_Larval_Habitat settings and just use what was stored in the serialized file. If Serialization_Mask_Node_Read = 16, then we create new habitats and ignore what is in the serialized file. We do use the x_Temporary_Larval_Habitat setting to adjust the habitat, but it is a known issue that we don’t also use LarvalHabitatMultiplier.

Can be changed

  • Altitude

  • BirthRate

  • Latitude

  • Longitude

  • NodePropertyValues

  • Airport

  • Region

  • Seaport

IndividualAttributes
Cannot be changed

  • AgeDistributionFlag, AgeDistribution1, AgeDistribution2

  • SusceptibilityDistributionFlag, SusceptibilityDistribution1, SusceptibilityDistribution2

  • PrevalenceDistributionFlag, PrevalenceDistribution1, PrevalenceDistribution2

Can be changed (with dependencies)

  • FertilityDistribution: If Birth_Rate_Dependence was serialized with the value INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR, then you can change this distribution.

  • MigrationHeterogeneityDistributionFlag, MigrationHeterogeneityDistribution1, MigrationHeterogeneityDistribution2: These values can be can be changed if Enable_Migration_Heterogeneity is set to 1 in config.json and Enable_Demographics_Birth was serialized true/on. Existing individuals will get new migration modifiers. For newborns to get it Enable_Demographics_Birth needed to be serialized with a value of 1.

  • MortalityDistributionFlag, MortalityDistribution1, MortalityDistribution2: These can be changed if Enable_Natural_Mortality was serialized as true/on. Which distribution is used depends on the serialized value of Death_Rate_Dependence.

  • RiskDistributionFlag, RiskDistribution1, RiskDistribution2: These can be changed if Enable_Demographics_Risk & Enable_Demographics_Birth were serialized as true/on. However, it will only impact newborns. If you had serialized Enable_Demographics_Risk and not Enable_Demographics_Birth, these parameters will do nothing.

IndividualProperties
Cannot be changed

  • Remove value from existing key You cannot remove an existing value from a key if the population that has been serialized has this value.

Can be changed

  • Add new value to existing key

  • Change Initial_Distribution You can change the Initial_Distribution if you just want to change the likelihood that a newborn will have a specific IndividualProperties value. It will not impact the how the IndividualProperties values are distributed in the population that is serialized.

Special cases

  • Add/Remove IP/Key Some may be changed, but it is not recommended. It is best practices to not add or remove IndividualProperties values unless you also update the serialized file. However, if you remove a value and do not ever reference it in the simulation that is running from the serialized file, the simulation may run without errors. If you add values and don’t add them to the people in the serialized file, then you should not reference it until all the people that came from the serialized file have died.

Changing serialized climate parameters

Climate data can be changed as it is not serialized. However, if the serialized file was created with weather data files, then it is best practices to save the file such that when the simulation is restarted the time of the year remains the same. For example, if you saved the file at the end of the dry season and start the simulation at the beginning of the dry season, the pressure on the vectors will be twice as long as normal and could impact results.

Note that currently only vector and malaria simulations utilize climate files.

There are couple ways to do this:

# Always save your serialized files on 365 day intervals. This way you know that the first day of the simulation that is reading from the file will start on January 1st. # Use the configuration parameter Start_Time to have the scenario start the day after the simulation was serialized. This can allow you to start right where you left off.

Editable climate parameters

  • Climate_Model

  • Climate_Update_Resolution

  • Enable_Climate_Stochasticity

  • Enable_Rainfall_Stochasticity

  • Air_Temperature_Variance

  • Land_Temperature_Variance

  • Relative_Humidity_Variance

Climate_Model = CLIMATE_CONSTANT

  • Base_Air_Temperature

  • Base_Land_Temperature

  • Base_Rainfall

  • Base_Relative_Humidity

Climate_Model = CLIMATE_BY_DATA

  • Air_Temperature_Filename

  • Land_Temperature_Filename

  • Rainfall_Filename

  • Relative_Humidity_Filename

  • Air_Temperature_Offset

  • Land_Temperature_Offset

  • Rainfall_Scale_Factor

  • Relative_Humidity_Scale_Factor

Climate_Model = CLIMATE_KOPPEN

  • Koppen_Filename

Changing serialized migration parameters

Not every parameter can be changed after the creation of serialized files. The following overview is intended as high-level guidance for what changes can and cannot be made.

Migration_Model

  • ON-to-OFF: If you turn it off, there will be no human migration even if the serialized file had trips planned or people were waiting to return.

  • OFF-to-ON:

    • If the file was serialized with migration off, and you set the Migration_Model to FIXED_RATE_MIGRATION and set Migration_Pattern to SINGLE_ROUND_TRIPS/RANDOM_WALK_DIFFUSION, then the migration will work as expected.

    • If the file was serialized with migration off, and you set Migration_Pattern = WAYPOINTS_HOME, then the serialized people will be fixed at one waypoint. Newborns will get the value of Roundtrip_Waypoints, but not the serialized people.

Migration_Pattern

This cannot be serialized. Changing the value will change behavior but not in a guaranteed way. For example, if you change it from SINGLE_ROUND_TRIPS to WAYPOINTS_HOME, Roundtrip_Waypoints is always 1 for the people that were serialized. Newborns should get the new value.

Note that while the type of Migration_Pattern cannot be changed, other migration parameters can be changed under specific circumstances.

Migration_Pattern = SINGLE_ROUND_TRIPS

The following parameters can be changed as long as Migration_Pattern was serialized as SINGLE_ROUND_TRIPS. Changing this parameter will not impact those people who have determined their return trip before the file was serialized. After de-serializing, new decisions to return will use these parameters.

  • Air_Migration_Roundtrip_Probability

  • Family_Migration_Roundtrip_Probability

  • Local_Migration_Roundtrip_Probability

  • Regional_Migration_Roundtrip_Probability

  • Sea_Migration_Roundtrip_Probability

  • Air_Migration_Roundtrip_Duration

  • Family_Migration_Roundtrip_Duration

  • Local_Migration_Roundtrip_Duration

  • Regional_Migration_Roundtrip_Duration

  • Sea_Migration_Roundtrip_Duration

Enable_X_Migration

This includes the parameters Enable_Local_Migration, Enable_Region_Migration, Enable_Air_Migration, Enable_Sea_Migration, and Enable_Family_Migration.

  • ON-to-OFF: If Migration_Model = FIXED_RATE_MIGRATION and you turn these off, existing plans for migration - both out and return - will still occur. However, no new migration plans will be made.

  • OFF-to-ON: People should start migrating as designed.

Roundtrip_Waypoints

This can be changed under certain circumstances. If you serialized with Migration_Pattern set to WAYPOINTS_HOME, you can change this but it will NOT change the number of waypoints for the people that were serialized. All the people being born after de-serializing will receive the new number of waypoints.

Changing reports in serialized simulations

Reports can be changed as they are not serialized. If a report has a channel that involves accumulating data over a period of time, it will start fresh with the new realization from the de-serialized data.

The following parameters can be changed:

  • Enable_Default_Reporting

  • Enable_Demographics_Reporting

  • Enable_Property_Output

  • Enable_Spatial_Output

  • Report_Event_Recorder

  • Enable_Vector_Species_Report

The following report parameters can be changed; their new values will only impact the reports in new realizations from the deserialized data:

  • Report_Detection_Threshold_Blood_Smear_Parasites

  • Report_Detection_Threshold_Blood_Smear_Gametocytes

  • Report_Detection_Threshold_PCR_Parasites

  • Report_Detection_Threshold_PCR_Gametocytes

  • Report_Detection_Threshold_PfHRP2

  • Report_Detection_Threshold_True_Parasite_Density

  • Report_Detection_Threshold_Fever

  • Report_Parasite_Smear_Sensitivity

  • Report_Gametocyte_Smear_Sensitivity

Output files (reports)

After the simulation finishes, a reporter extracts simulation data, aggregates it, and outputs it to a file (known as an output report). Most of the reports are also JSON files, the most important of which is InsetChart.json. The InsetChart.json file provides simulation-wide averages of disease prevalence at each time step.

After running a simulation, the simulation data is extracted, aggregated, and saved as an output report to the output directory in the working directory. Depending on your configuration, one or more output reports will be created, each of which summarize different data from the simulation. Output reports can be in JSON, CSV, or binary file formats. EMOD also creates logging or error output files.

The EMOD functionality that produces an output report is known as a reporter. EMOD provides several built-in reporters for outputting data from simulations. By default, EMOD will always generate the report InsetChart.json, which contains the simulation-wide average disease prevalence by time step. If none of the provided reports generates the output report that you require, you can create a custom reporter.

_images/output.png

If you want to visualize the data output from an EMOD simulation, you must use graphing software to plot the output reports. In addition to output reports, EMOD will generate error and logging files to help troubleshoot any issues you may encounter.

Using output reports

By default, the output report InsetChart.json is always produced, which contains per- time step values accumulated over the simulation in a variety of reporting channels, such as new infections, prevalence, and recovered. EMOD provides several other built-in reports that you can produce if you enable them in the configuration file with the Output settings parameters. Reports are generally in JSON or CSV format. If none of the built-in output reports provide the data you need, you can use a custom reporter that plugs in to the Eradication.exe as an EMODule dynamic link library (DLL). For more information, see Custom reporters.

In order to interpret the output of EMOD simulations, you will find it useful to parse the output reports into an analyzable structure. For example, you can use a Python or MATLAB script to create graphs and charts for analysis.

Convert output to CSV format

Most output reports, including the primary InsetChart report, are in JSON format. If you are using R for data analysis, you may prefer a CSV report. You can easily convert the output format using Python post-processing using the icjjson2csv.py script provided in the EMOD GitHub repository. Provide the path to this script using the -P argument when you run Eradication.exe at the command line. See Run a simulation using the command line for more information.

Use Python to plot data

The example below uses the Python package JSON to parse the file and the Python package matplotlib.pyplot to plot the output. This is a very simple example and not likely the most robust or elegant. Be sure to set the actual path to your working directory.

import os
import json
import matplotlib.pyplot as plt

# open and parse InsetChart.json
ic_json = json.loads( open( os.path.join( WorkingDirectoryLocation, "output", "InsetChart.json" ) ).read() )
ic_json_allchannels = ic_json["Channels"]
ic_json_birthdata = ic_json["Channels"]["Births"]

# plot "Births" channel by time step
plt.plot( ic_json_birthdata[  "Data"  ], 'b-' )
plt.title( "Births" )
plt.show()
Use MATLAB to plot data

The example below uses the MATLAB toolbox JSONlab to parse an InsetChart.json file and plot one channel. This script uses JSONLab to parse the file into a usable form in MATLAB. This is a very simple example and not likely the most robust or elegant. Be sure to set the actual paths to JSONlab and your working directory.

% this sample uses JSONLab toolbox
addpath('PATH TO/jsonlab');

% open and parse InsetChart.json
ic_json = loadjson( fullfile( 'WorkingDirectoryLocation', 'output', 'InsetChart.json' ));
ic_json_allchannels = ic_json.Channels;
ic_json_birthinfo = ic_json_allchannels.Births;
ic_json_birthdata = ic_json_birthinfo.Data;
M = num2cell(ic_json_birthdata);

% plot "Births" channel by time step
plot(cell2mat(M));
title( 'Births' );
Custom reporters

Reporters extract simulation data, aggregate it, and output it to a file known as an output report. You can process the report data using tools, such as Python or MATLAB, to create graphs and charts for analysis. EMOD provides built-in reporters that are part of the EMOD executable (Eradication.exe) and can be enabled or disabled by setting parameters in the configuration file. See Output files (reports) for a list of the reports that are available using built-in reporters.

In addition, you can use custom reporters that extract data from the simulation and aren’t part of the Eradication.exe. A custom reporter is an EMODule that you plug in to EMOD. Custom reporters are not supported for CentOS. There are several reporters in the GitHub reporters directory that you can use. You may also want to build your own custom reporter to create a new output report.

_images/Reporters.png

The Eradication.exe must load the reporter when running a simulation to use it. If it is loaded, the output report will be automatically generated at the end of the simulation. There are three ways to specify their location so Eradication.exe can load them. Eradication.exe attempts to load the file using the following methods, in the order listed:

  1. Define the location of the dynamic link library (DLL) in a JSON-formatted file (emodules_map.json).

  2. Point to the location using the --dll-path command-line option when invoking Eradication.exe.

  3. Place the DLL in the working directory.

JSON file

First, Eradication.exe looks for an emodules_map.json file in the working directory. This map file lists specific reporter DLLs and their exact location. This is useful if you want to store all custom reporters in the same directory, but only want certain reporters to be used with each simulation.

The emodules_map.json file has three sections: diseases, interventions and reporters. Each section is a JSON array and contains the path to each EMODule in the array. Although reporter EMODules are the only type currently supported, empty disease and intervention sections must be included. You must use either a double backslash (\\) or a single forward slash (/) to represent a single backslash for the path. For example:

{
    "disease_plugins": [
         ],
    "interventions": [
         ],
    "reporter_plugins": [
        "C:\\src\\EMOD\\x64\\Release\\emodules\\reporter_plugins\\libreportpluginbasic.dll"
    ]
}
Command-line option

If a map file is not provided, you can include the --dll-path option when you invoke Eradication.exe. It must point to a directory with a reporter_plugins subdirectory that contains the reporters. The name of the directory does not matter, but the reporter must be in a subdirectory named reporter_plugins. Note that this method will load all reporters in the root directory specified.

If you build custom reporters as described here, the DLLs will be saved to the following directories, depending on the build configuration:

  • <EMOD source directory path>x64Releasereporter_plugins

  • <EMOD source directory path>x64Debugreporter_plugins

Therefore, if you do not move your reports, you will set --dll-path to one of the following paths:

  • <EMOD source directory path>x64Release

  • <EMOD source directory path>x64Debug

For more information on EMOD command-line options, see Run a simulation using the command line.

Working directory

Finally, if neither the the map file or the command-line option are provided, Eradication.exe looks for the reporter plug-in in the current working directory.

Error and logging files

When you run a simulation, EMOD will output basic error and logging information to help track the progress and help debug any issues that may occur. If you run the simulation on an HPC cluster, the cluster will generate additional logging and error files. See Troubleshooting EMOD simulations if you need help resolving an error.

Status

A status.txt file will be saved to the working directory that provides one output line per time step and includes the total run time of the simulation. A simulation with 50 time steps will look something like this:

Beginning Simulation...
1 of 50 steps complete.
2 of 50 steps complete.
3 of 50 steps complete.
4 of 50 steps complete.
5 of 50 steps complete.
6 of 50 steps complete.
7 of 50 steps complete.
8 of 50 steps complete.
9 of 50 steps complete.
10 of 50 steps complete.
11 of 50 steps complete.
12 of 50 steps complete.
13 of 50 steps complete.
14 of 50 steps complete.
15 of 50 steps complete.
16 of 50 steps complete.
17 of 50 steps complete.
18 of 50 steps complete.
19 of 50 steps complete.
20 of 50 steps complete.
21 of 50 steps complete.
22 of 50 steps complete.
23 of 50 steps complete.
24 of 50 steps complete.
25 of 50 steps complete.
26 of 50 steps complete.
27 of 50 steps complete.
28 of 50 steps complete.
29 of 50 steps complete.
30 of 50 steps complete.
31 of 50 steps complete.
32 of 50 steps complete.
33 of 50 steps complete.
34 of 50 steps complete.
35 of 50 steps complete.
36 of 50 steps complete.
37 of 50 steps complete.
38 of 50 steps complete.
39 of 50 steps complete.
40 of 50 steps complete.
41 of 50 steps complete.
42 of 50 steps complete.
43 of 50 steps complete.
44 of 50 steps complete.
45 of 50 steps complete.
46 of 50 steps complete.
47 of 50 steps complete.
48 of 50 steps complete.
49 of 50 steps complete.
50 of 50 steps complete.
Done - 0:00:02
Standard output

When you run a simulation on an HPC cluster, it will generate a standard output logging file (StdOut.txt) in the working directory that captures all standard output messages. When you run a simulation locally, the Command Prompt window will display the same information. If you want to save this information to a text file instead, you can append > stdout.txt to the command used to run the local EMOD simulation to redirect the console output to the file specified.

The file contains information about a particular simulation, such as the EMOD version used and the files in use, as well as other initialization information, including the default logging level and the logging levels set for particular modules. The file follows that information with log output using the following format: <timestep><HPC rank><log level><module><message>.

By default, the logging level is set to “INFO”. If you want to change the logging level, see Set log levels.

For example:

..\..\..\Eradication.exe --config config.json --input-path ..\..\..\Demographics_Files
Intellectual Ventures(R)/EMOD Disease Transmission Kernel 2.18.16.0
Built on Jul  5 2018 15:32:59 by SYSTEM from master (e98fbf4) checked in on 2018-06-12 11:32:40 -0700
Supports sim_types: GENERIC, VECTOR, MALARIA, AIRBORNE, TBHIV, STI, HIV, PY.
Using config file: config.json
Using input path: ..\..\..\Demographics_Files
Using output path: output
Using dll path:
Python not initialized because --python-script-path (-P) not set.
Initializing environment...
Log-levels:
        Default -> INFO
        Eradication -> INFO
00:00:00 [0] [I] [Eradication] Loaded Configuration...
00:00:00 [0] [I] [Eradication] 56 parameters found.
00:00:00 [0] [I] [Eradication] Initializing Controller...
00:00:00 [0] [I] [Controller] DefaultController::execute_internal()...
00:00:00 [0] [I] [Simulation] Using PSEUDO_DES random number generator.
00:00:00 [0] [I] [DllLoader] ReadEmodulesJson: no file, returning.
00:00:00 [0] [I] [DllLoader] dllPath not passed in, getting from EnvPtr
00:00:00 [0] [I] [DllLoader] Trying to copy from string to wstring.
00:00:00 [0] [I] [DllLoader] DLL ws root path:
00:00:00 [0] [W] [Simulation] 00:00:00 [0] [W] [Simulation] Failed to load reporter emodules for SimType: GENERIC_SIM from path: reporter_plugins
Failed to load reporter emodules for SimType: GENERIC_SIM from path: reporter_plugins
00:00:00 [0] [I] [Simulation] Found 0 Custom Report DLL's to consider loading, load_all_reports=1
00:00:00 [0] [I] [Controller] DefaultController::execute_internal() populate simulation...
00:00:00 [0] [I] [Simulation] Campaign file name identified as: campaign.json
00:00:00 [0] [I] [Climate] Initialize
00:00:00 [0] [I] [LoadBalanceScheme] Using Checkerboard Load Balance Scheme.
00:00:00 [0] [I] [Simulation] Looking for campaign file campaign.json
00:00:00 [0] [I] [Simulation] Found campaign file successfully.
00:00:00 [0] [I] [DllLoader] ReadEmodulesJson: no file, returning.
00:00:00 [0] [I] [DllLoader] dllPath not passed in, getting from EnvPtr
00:00:00 [0] [I] [DllLoader] Trying to copy from string to wstring.
00:00:00 [0] [I] [DllLoader] DLL ws root path:
00:00:00 [0] [W] [Simulation] 00:00:00 [0] [W] [Simulation] Failed to load intervention emodules for SimType: GENERIC_SIM from path: interventions
Failed to load intervention emodules for SimType: GENERIC_SIM from path: interventions
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Number_Repetitions" : 1 ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Timesteps_Between_Repetitions" : -1 ) for unspecified parameter.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Incubation_Period_Override" : -1 ) for unspecified parameter.
00:00:01 [0] [I] [Simulation] populateFromDemographics() created 1 nodes
00:00:01 [0] [I] [Simulation] populateFromDemographics() generated 1 nodes.
00:00:01 [0] [I] [Simulation] Rank 0 contributes 1 nodes...
00:00:01 [0] [I] [Simulation] Merging node rank maps...
00:00:01 [0] [I] [Simulation] Merged rank 0 map now has 1 nodes.
00:00:01 [0] [I] [Simulation] Rank map contents not displayed until NodeRankMap::ToString() (re)implemented.
00:00:01 [0] [I] [Simulation] Initialized 'InsetChart.json' reporter
00:00:01 [0] [I] [Simulation] Initialized 'BinnedReport.json' reporter
00:00:01 [0] [I] [Simulation] Initialized 'DemographicsSummary.json' reporter
00:00:01 [0] [I] [Simulation] Update(): Time: 1.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [SimulationEventContext] Time for campaign event. Calling Dispatch...
00:00:01 [0] [I] [SimulationEventContext] 1 node(s) visited.
00:00:01 [0] [I] [JsonConfigurable] Using the default value ( "Incubation_Period_Override" : -1 ) for unspecified parameter.
00:00:01 [0] [I] [StandardEventCoordinator] UpdateNodes() gave out 4 'OutbreakIndividual' interventions at node 1
00:00:01 [0] [I] [Simulation] Update(): Time: 2.0 Rank: 0 StatPop: 10000 Infected: 4
00:00:01 [0] [I] [Simulation] Update(): Time: 3.0 Rank: 0 StatPop: 10000 Infected: 13
00:00:01 [0] [I] [Simulation] Update(): Time: 4.0 Rank: 0 StatPop: 10000 Infected: 65
00:00:01 [0] [I] [Simulation] Update(): Time: 5.0 Rank: 0 StatPop: 10000 Infected: 283
00:00:01 [0] [I] [Simulation] Update(): Time: 6.0 Rank: 0 StatPop: 10000 Infected: 1149
00:00:01 [0] [I] [Simulation] Update(): Time: 7.0 Rank: 0 StatPop: 10000 Infected: 3777
00:00:01 [0] [I] [Simulation] Update(): Time: 8.0 Rank: 0 StatPop: 10000 Infected: 7268
00:00:01 [0] [I] [Simulation] Update(): Time: 9.0 Rank: 0 StatPop: 10000 Infected: 7065
00:00:01 [0] [I] [Simulation] Update(): Time: 10.0 Rank: 0 StatPop: 10000 Infected: 5578
00:00:01 [0] [I] [Simulation] Update(): Time: 11.0 Rank: 0 StatPop: 10000 Infected: 4377
00:00:01 [0] [I] [Simulation] Update(): Time: 12.0 Rank: 0 StatPop: 10000 Infected: 3392
00:00:01 [0] [I] [Simulation] Update(): Time: 13.0 Rank: 0 StatPop: 10000 Infected: 2640
00:00:01 [0] [I] [Simulation] Update(): Time: 14.0 Rank: 0 StatPop: 10000 Infected: 2054
00:00:01 [0] [I] [Simulation] Update(): Time: 15.0 Rank: 0 StatPop: 10000 Infected: 1624
00:00:01 [0] [I] [Simulation] Update(): Time: 16.0 Rank: 0 StatPop: 10000 Infected: 1247
00:00:01 [0] [I] [Simulation] Update(): Time: 17.0 Rank: 0 StatPop: 10000 Infected: 975
00:00:01 [0] [I] [Simulation] Update(): Time: 18.0 Rank: 0 StatPop: 10000 Infected: 742
00:00:01 [0] [I] [Simulation] Update(): Time: 19.0 Rank: 0 StatPop: 10000 Infected: 605
00:00:01 [0] [I] [Simulation] Update(): Time: 20.0 Rank: 0 StatPop: 10000 Infected: 469
00:00:01 [0] [I] [Simulation] Update(): Time: 21.0 Rank: 0 StatPop: 10000 Infected: 355
00:00:01 [0] [I] [Simulation] Update(): Time: 22.0 Rank: 0 StatPop: 10000 Infected: 267
00:00:01 [0] [I] [Simulation] Update(): Time: 23.0 Rank: 0 StatPop: 10000 Infected: 206
00:00:01 [0] [I] [Simulation] Update(): Time: 24.0 Rank: 0 StatPop: 10000 Infected: 164
00:00:01 [0] [I] [Simulation] Update(): Time: 25.0 Rank: 0 StatPop: 10000 Infected: 122
00:00:01 [0] [I] [Simulation] Update(): Time: 26.0 Rank: 0 StatPop: 10000 Infected: 89
00:00:01 [0] [I] [Simulation] Update(): Time: 27.0 Rank: 0 StatPop: 10000 Infected: 73
00:00:01 [0] [I] [Simulation] Update(): Time: 28.0 Rank: 0 StatPop: 10000 Infected: 57
00:00:01 [0] [I] [Simulation] Update(): Time: 29.0 Rank: 0 StatPop: 10000 Infected: 46
00:00:01 [0] [I] [Simulation] Update(): Time: 30.0 Rank: 0 StatPop: 10000 Infected: 32
00:00:01 [0] [I] [Simulation] Update(): Time: 31.0 Rank: 0 StatPop: 10000 Infected: 22
00:00:01 [0] [I] [Simulation] Update(): Time: 32.0 Rank: 0 StatPop: 10000 Infected: 17
00:00:01 [0] [I] [Simulation] Update(): Time: 33.0 Rank: 0 StatPop: 10000 Infected: 16
00:00:01 [0] [I] [Simulation] Update(): Time: 34.0 Rank: 0 StatPop: 10000 Infected: 15
00:00:01 [0] [I] [Simulation] Update(): Time: 35.0 Rank: 0 StatPop: 10000 Infected: 10
00:00:01 [0] [I] [Simulation] Update(): Time: 36.0 Rank: 0 StatPop: 10000 Infected: 6
00:00:01 [0] [I] [Simulation] Update(): Time: 37.0 Rank: 0 StatPop: 10000 Infected: 4
00:00:01 [0] [I] [Simulation] Update(): Time: 38.0 Rank: 0 StatPop: 10000 Infected: 3
00:00:01 [0] [I] [Simulation] Update(): Time: 39.0 Rank: 0 StatPop: 10000 Infected: 3
00:00:01 [0] [I] [Simulation] Update(): Time: 40.0 Rank: 0 StatPop: 10000 Infected: 2
00:00:01 [0] [I] [Simulation] Update(): Time: 41.0 Rank: 0 StatPop: 10000 Infected: 1
00:00:01 [0] [I] [Simulation] Update(): Time: 42.0 Rank: 0 StatPop: 10000 Infected: 1
00:00:01 [0] [I] [Simulation] Update(): Time: 43.0 Rank: 0 StatPop: 10000 Infected: 1
00:00:01 [0] [I] [Simulation] Update(): Time: 44.0 Rank: 0 StatPop: 10000 Infected: 1
00:00:01 [0] [I] [Simulation] Update(): Time: 45.0 Rank: 0 StatPop: 10000 Infected: 1
00:00:01 [0] [I] [Simulation] Update(): Time: 46.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 47.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 48.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 49.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 50.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 51.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 52.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:01 [0] [I] [Simulation] Update(): Time: 53.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 54.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 55.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 56.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 57.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 58.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 59.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 60.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 61.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 62.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 63.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 64.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 65.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 66.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 67.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 68.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 69.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 70.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 71.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 72.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 73.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 74.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 75.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 76.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 77.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 78.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 79.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 80.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 81.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 82.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 83.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 84.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 85.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 86.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 87.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 88.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 89.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Update(): Time: 90.0 Rank: 0 StatPop: 10000 Infected: 0
00:00:02 [0] [I] [Simulation] Finalizing 'InsetChart.json' reporter.
00:00:02 [0] [I] [Simulation] Finalized  'InsetChart.json' reporter.
00:00:02 [0] [I] [Simulation] Finalizing 'BinnedReport.json' reporter.
00:00:02 [0] [I] [Simulation] Finalized  'BinnedReport.json' reporter.
00:00:02 [0] [I] [Simulation] Finalizing 'DemographicsSummary.json' reporter.
00:00:02 [0] [I] [Simulation] Finalized  'DemographicsSummary.json' reporter.
00:00:02 [0] [I] [Controller] Exiting DefaultController::execute_internal
00:00:02 [0] [I] [Eradication] Controller executed successfully.
Standard error

When you run a simulation on an HPC cluster, it will also generate a standard error logging file (StdErr.txt) in the working directory that captures all standard error messages.

BinnedReport

The binned output report (BinnedReport.json) is a JSON-formatted file where the channel data has been sorted into age bins. It is very similar to an inset chart, however, with the binned report all channels are broken down into sub-channels (bins) based on age. For example, instead of having a single prevalence channel, you might have prevalence in the “0-3 years old bin” and the “4-6 years old bin, and so forth.

To generate the binned report, set the Enable_Demographics_Reporting configuration parameter to 1. The demographics summary output report will also be generated.

The file contains a header and a channels section.

Channels

The channels section contains the following parameters.

Parameter

Data type

Description

<Channel_Title>

string

The title of the particular channel.

Units

string

The units used for this channel.

Data

array

A list of the channel data at each time step.
Example

The following is a sample of a BinnedReport.json file.

{
    "Header": {
        "DateTime": "Wed Oct 01 14:49:22 2014",
        "DTK_Version": "4284 trunk 2014/09/23 11:50:52",
        "Report_Version": "2.1",
        "Timesteps": 150,
        "Subchannel_Metadata": {
            "AxisLabels": [
                ["Age"]
            ],
            "NumBinsPerAxis": [
                [21]
            ],
            "ValuesPerAxis": [
                [
                    [1825, 3650, 5475, 7300, 9125, 10950, 12775, 14600, 16425, 18250, 20075, 21900, 23725, 25550, 27375, 29200, 31025, 32850, 34675, 36500, 999999]
                ]
            ],
            "MeaningPerAxis": [
                [
                    ["<5", "5-9", "10-14", "15-19", "20-24", "25-29", "30-34", "35-39", "40-44", "45-49", "50-54", "55-59", "60-64", "65-69", "70-74", "75-79", "80-84", "85-89", "90-94", "95-99", ">100"]
                ]
            ]
        },
        "Channels": 4
    },
    "Channels": {
        "Disease Deaths": {
            "Units": "",
            "Data": [
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
            ]
        },
        "Infected": {
            "Units": "",
            "Data": [
                [0, 2, 1, 1, 1, 1, 2, 6, 7, 5, 3, 5, 4, 3, 2, 3, 5, 6, 14, 21, 22, 22, 31, 52, 63, 101, 108, 119, 121, 139, 132, 133, 130, 115, 97, 95, 93, 98, 102, 108, 105, 110, 98, 90, 93, 94, 92, 81, 62, 57, 63, 56, 58, 61, 67, 64, 52, 54, 45, 33, 34, 36, 27, 32, 29, 21, 17, 7, 13, 15, 17, 13, 14, 11, 14, 15, 11, 12, 7, 6, 6, 3, 3, 3, 4, 4, 3, 3, 2, 2, 3, 3, 4, 2, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 3, 4, 2, 2, 2, 1, 5, 5, 7, 7, 6, 13, 14, 12, 8, 8, 15, 15, 23, 39, 43, 61, 82, 110, 133, 142, 133, 113, 105, 105, 100, 86, 81, 81, 75, 73, 68, 74, 74, 73, 70, 75, 67, 63, 72, 61, 63, 60, 55, 52, 47, 44, 36, 39, 36, 39, 36, 28, 27, 22, 20, 17, 20, 22, 17, 13, 13, 10, 10, 6, 7, 7, 3, 4, 5, 5, 4, 2, 1, 2, 2, 2, 3, 2, 2, 4, 2, 1, 2, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 1, 2, 3, 3, 4, 3, 3, 3, 2, 2, 3, 5, 5, 7, 7, 12, 15, 21, 24, 22, 23, 33, 36, 42, 58, 93, 95, 104, 105, 102, 83, 75, 72, 67, 66, 63, 68, 61, 61, 63, 62, 60, 67, 67, 55, 52, 55, 42, 43, 40, 43, 36, 37, 30, 33, 33, 29, 23, 20, 15, 15, 17, 16, 14, 13, 13, 12, 15, 13, 11, 7, 13, 12, 11, 10, 9, 6, 5, 7, 4, 7, 4, 2, 2, 2, 1, 0, 0, 0, 1, 0, 1, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 0, 0, 0, 0, 0, 1, 2, 3, 4, 2, 3, 2, 4, 6, 7, 10, 12, 13, 14, 16, 18, 27, 31, 50, 50, 48, 58, 68, 86, 81, 82, 76, 67, 58, 58, 59, 63, 57, 47, 40, 48, 43, 46, 45, 46, 46, 44, 40, 39, 40, 40, 37, 39, 36, 29, 26, 20, 22, 23, 20, 15, 13, 16, 16, 14, 12, 10, 7, 9, 8, 6, 6, 5, 3, 3, 3, 2, 1, 1, 1, 1, 1, 2, 3, 3, 2, 2, 1, 1, 0, 1, 2, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 2, 1, 2, 2, 2, 2, 4, 5, 4, 5, 4, 2, 4, 9, 11, 12, 16, 15, 20, 22, 28, 40, 44, 44, 48, 54, 54, 50, 53, 52, 51, 48, 47, 43, 44, 40, 40, 43, 36, 34, 30, 34, 32, 29, 26, 27, 24, 16, 22, 21, 18, 18, 17, 17, 15, 12, 14, 9, 12, 5, 6, 3, 6, 7, 6, 8, 9, 8, 7, 7, 6, 5, 4, 3, 5, 5, 4, 3, 3, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 1, 1, 2, 2, 2, 1, 1, 1, 0, 0, 1, 2, 3, 1, 2, 2, 7, 7, 9, 10, 10, 19, 22, 34, 44, 42, 45, 62, 63, 48, 48, 48, 46, 42, 37, 33, 33, 33, 35, 34, 37, 34, 33, 30, 28, 32, 33, 24, 27, 27, 23, 25, 18, 12, 13, 12, 12, 11, 9, 5, 6, 7, 8, 10, 7, 7, 5, 6, 5, 5, 5, 4, 6, 5, 2, 3, 5, 4, 4, 1, 1, 1, 2, 2, 2, 2, 2, 1, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 3, 2, 5, 11, 16, 20, 25, 25, 26, 36, 53, 49, 48, 51, 54, 47, 44, 35, 30, 21, 20, 22, 24, 26, 28, 22, 16, 19, 31, 26, 30, 25, 30, 26, 19, 22, 21, 18, 21, 23, 15, 11, 11, 11, 9, 6, 4, 2, 4, 4, 3, 2, 2, 4, 3, 3, 4, 3, 2, 1, 1, 0, 0, 3, 3, 2, 4, 3, 2, 1, 1, 1, 1, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2, 1, 3, 2, 1, 1, 2, 3, 10, 13, 12, 12, 17, 26, 24, 23, 25, 30, 33, 28, 35, 34, 27, 22, 22, 21, 22, 19, 18, 16, 13, 17, 13, 14, 11, 14, 11, 11, 10, 12, 14, 13, 13, 15, 12, 9, 7, 6, 5, 5, 5, 6, 6, 7, 8, 6, 6, 5, 4, 4, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 3, 3, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 2, 2, 1, 1, 2, 2, 0, 0, 0, 0, 2, 3, 5, 7, 5, 4, 10, 8, 10, 11, 18, 18, 21, 27, 27, 26, 24, 20, 24, 24, 21, 20, 21, 20, 19, 21, 18, 21, 13, 12, 14, 15, 13, 12, 14, 15, 13, 9, 8, 7, 6, 4, 8, 6, 4, 3, 4, 5, 5, 3, 1, 1, 1, 1, 0, 1, 1, 1, 3, 2, 3, 2, 1, 2, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 2, 2, 3, 5, 7, 7, 9, 13, 13, 16, 20, 18, 22, 26, 26, 23, 23, 24, 20, 13, 7, 7, 11, 9, 12, 13, 16, 19, 20, 14, 11, 12, 11, 10, 11, 8, 6, 6, 4, 4, 2, 6, 6, 4, 4, 3, 3, 3, 6, 6, 6, 4, 4, 3, 4, 2, 3, 5, 3, 4, 2, 2, 4, 4, 5, 3, 3, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 1, 1, 0, 0, 1, 2, 0, 0, 0, 1, 1, 2, 2, 2, 2, 1, 0, 1, 2, 3, 3, 5, 5, 4, 6, 15, 16, 18, 22, 22, 22, 23, 12, 8, 5, 6, 4, 5, 6, 9, 10, 11, 13, 17, 14, 11, 13, 13, 9, 7, 6, 11, 9, 7, 4, 4, 3, 2, 2, 3, 1, 4, 3, 2, 1, 2, 4, 2, 2, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 1, 1, 3, 2, 3, 2, 2, 4, 3, 8, 11, 10, 12, 10, 6, 6, 12, 9, 5, 6, 6, 9, 8, 6, 8, 7, 8, 12, 11, 11, 7, 14, 13, 12, 11, 12, 6, 8, 10, 12, 8, 4, 4, 2, 3, 3, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 2, 1, 0, 0, 0, 1, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 0, 1, 3, 4, 6, 9, 9, 11, 12, 12, 11, 12, 12, 9, 9, 6, 7, 8, 10, 10, 11, 4, 8, 7, 10, 9, 9, 10, 8, 6, 4, 3, 2, 2, 3, 3, 5, 7, 4, 4, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 0, 1, 1, 1, 1, 2, 2, 2, 4, 4, 4, 4, 6, 4, 8, 9, 7, 6, 7, 6, 6, 5, 5, 4, 2, 4, 4, 4, 4, 4, 6, 5, 3, 2, 3, 4, 2, 1, 2, 4, 6, 6, 6, 5, 2, 3, 4, 2, 1, 3, 3, 3, 3, 2, 2, 0, 0, 0, 0, 0, 1, 1, 2, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2, 1, 2, 2, 4, 5, 10, 9, 10, 10, 10, 8, 10, 9, 9, 8, 7, 7, 4, 5, 5, 6, 4, 3, 4, 2, 4, 4, 4, 5, 4, 2, 3, 2, 4, 2, 2, 2, 0, 0, 1, 2, 1, 1, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 2, 2, 1, 2, 2, 1, 1, 2, 3, 4, 3, 4, 6, 6, 3, 4, 2, 1, 2, 3, 3, 4, 2, 2, 4, 6, 4, 3, 2, 2, 2, 3, 4, 5, 4, 5, 4, 4, 3, 5, 5, 4, 4, 3, 3, 3, 2, 3, 3, 3, 3, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 3, 6, 8, 8, 5, 5, 5, 6, 3, 4, 4, 5, 6, 6, 6, 4, 2, 2, 2, 2, 4, 2, 3, 3, 5, 6, 6, 6, 4, 3, 2, 2, 0, 2, 1, 1, 0, 0, 0, 0, 2, 2, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 4, 6, 7, 7, 7, 6, 5, 5, 4, 4, 4, 1, 1, 1, 1, 2, 1, 1, 0, 0, 1, 2, 1, 2, 3, 2, 1, 2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 2, 1, 1, 1, 2, 5, 4, 5, 3, 3, 1, 1, 1, 1, 1, 0, 1, 1, 0, 0, 2, 2, 1, 2, 2, 2, 3, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 2, 2, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 3, 3, 4, 3, 4, 4, 5, 5, 3, 1, 1, 1, 1, 3, 2, 2, 2, 1, 1, 2, 2, 2, 2, 2, 2, 1, 2, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 1, 2, 2, 2, 3, 9, 9, 10, 15, 12, 8, 8, 11, 12, 12, 9, 6, 5, 9, 8, 10, 11, 11, 7, 5, 4, 5, 5, 5, 3, 0, 1, 3, 6, 7, 4, 4, 2, 1, 1, 2, 2, 2, 1, 1, 0, 1, 1, 1, 2, 2, 2, 2, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
            ]
        },
        "New Infections": {
            "Units": "",
            "Data": [
                [0, 2, 0, 0, 0, 0, 1, 4, 1, 0, 0, 3, 1, 1, 1, 2, 3, 1, 11, 14, 5, 9, 15, 30, 28, 50, 34, 47, 42, 48, 46, 36, 37, 17, 25, 33, 22, 31, 33, 37, 28, 36, 21, 21, 27, 26, 28, 15, 14, 20, 21, 15, 17, 19, 23, 17, 7, 15, 10, 10, 7, 14, 2, 13, 10, 1, 2, 0, 8, 4, 6, 1, 4, 3, 4, 4, 1, 3, 2, 1, 3, 0, 1, 1, 1, 1, 0, 1, 1, 0, 2, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 3, 1, 0, 0, 1, 0, 5, 0, 3, 1, 2, 7, 6, 4, 3, 2, 11, 9, 15, 19, 16, 30, 34, 46, 51, 49, 39, 27, 32, 37, 22, 23, 19, 25, 17, 28, 15, 25, 28, 25, 22, 24, 17, 15, 25, 13, 24, 17, 14, 17, 12, 14, 11, 19, 9, 11, 10, 5, 8, 5, 6, 3, 6, 5, 4, 2, 6, 1, 2, 1, 2, 2, 0, 2, 2, 2, 1, 0, 1, 1, 0, 1, 1, 0, 1, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 0, 3, 1, 5, 6, 8, 6, 9, 7, 19, 12, 19, 30, 46, 25, 35, 35, 33, 21, 23, 19, 20, 12, 21, 19, 15, 19, 16, 14, 20, 17, 17, 6, 15, 14, 14, 14, 12, 11, 7, 10, 6, 9, 8, 7, 3, 4, 3, 5, 5, 4, 6, 7, 3, 3, 6, 2, 2, 2, 7, 0, 2, 2, 2, 2, 1, 2, 0, 4, 0, 0, 2, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 0, 0, 0, 0, 0, 1, 1, 2, 1, 0, 1, 1, 2, 2, 2, 4, 3, 5, 4, 5, 8, 13, 10, 23, 18, 19, 23, 26, 32, 26, 21, 15, 9, 16, 17, 17, 16, 17, 13, 9, 19, 10, 15, 11, 15, 12, 13, 10, 16, 13, 9, 13, 13, 4, 6, 7, 6, 8, 2, 4, 2, 5, 5, 4, 3, 5, 3, 1, 5, 0, 0, 2, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 2, 1, 0, 1, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 2, 0, 1, 1, 0, 0, 2, 1, 1, 2, 0, 0, 2, 6, 2, 4, 6, 6, 6, 10, 12, 20, 16, 15, 20, 16, 18, 14, 15, 14, 12, 13, 12, 9, 13, 10, 13, 11, 9, 9, 6, 15, 9, 9, 7, 8, 7, 6, 8, 6, 6, 3, 5, 5, 4, 4, 4, 0, 4, 0, 3, 0, 3, 2, 1, 3, 4, 0, 0, 3, 1, 2, 1, 1, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 1, 1, 5, 2, 2, 3, 5, 10, 9, 17, 15, 14, 14, 26, 20, 11, 14, 10, 14, 10, 8, 11, 9, 12, 13, 7, 12, 11, 9, 11, 8, 12, 7, 7, 9, 6, 6, 5, 2, 4, 3, 3, 7, 2, 0, 2, 2, 3, 4, 3, 0, 1, 0, 1, 1, 2, 2, 0, 3, 1, 1, 1, 2, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 3, 6, 6, 6, 6, 9, 12, 17, 25, 14, 14, 17, 12, 8, 12, 10, 9, 2, 8, 5, 11, 9, 7, 4, 2, 11, 15, 4, 11, 4, 9, 6, 3, 12, 4, 2, 6, 6, 3, 2, 4, 2, 1, 1, 0, 0, 3, 0, 0, 0, 0, 2, 1, 1, 1, 0, 0, 1, 0, 0, 0, 3, 0, 0, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0, 0, 2, 0, 0, 0, 1, 1, 8, 3, 2, 5, 7, 13, 6, 9, 8, 10, 10, 4, 13, 8, 8, 5, 6, 9, 6, 5, 5, 4, 5, 7, 2, 6, 3, 7, 2, 5, 2, 5, 5, 5, 4, 5, 2, 1, 2, 1, 2, 1, 1, 1, 1, 2, 3, 0, 1, 2, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 2, 0, 0, 0, 1, 0, 0, 0, 0, 0, 2, 2, 2, 2, 1, 1, 7, 0, 5, 3, 10, 6, 8, 12, 3, 10, 5, 6, 10, 8, 4, 4, 5, 6, 2, 4, 3, 7, 2, 1, 6, 5, 5, 4, 6, 3, 3, 3, 3, 1, 1, 1, 4, 1, 1, 1, 2, 1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 2, 0, 2, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 1, 1, 2, 3, 3, 2, 4, 4, 6, 7, 8, 10, 8, 6, 7, 4, 4, 1, 3, 0, 7, 4, 5, 6, 5, 4, 6, 7, 3, 4, 4, 2, 2, 3, 0, 1, 1, 0, 2, 0, 4, 2, 1, 0, 1, 1, 1, 3, 0, 1, 1, 0, 1, 1, 0, 1, 2, 0, 2, 0, 1, 2, 1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 1, 0, 0, 0, 1, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 1, 2, 1, 2, 1, 3, 4, 9, 5, 7, 7, 3, 6, 5, 1, 1, 2, 2, 2, 2, 2, 3, 3, 4, 5, 7, 0, 2, 4, 2, 0, 1, 1, 7, 1, 1, 1, 2, 0, 0, 1, 1, 0, 3, 0, 0, 0, 1, 2, 1, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 2, 0, 1, 1, 0, 3, 2, 5, 4, 3, 5, 2, 2, 4, 6, 1, 1, 1, 2, 3, 3, 1, 3, 1, 3, 5, 4, 3, 1, 8, 1, 4, 1, 3, 0, 4, 3, 3, 3, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 2, 1, 2, 5, 3, 6, 3, 4, 4, 5, 3, 2, 2, 1, 2, 2, 4, 2, 4, 0, 5, 4, 4, 1, 3, 4, 1, 1, 0, 0, 0, 1, 2, 1, 2, 3, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1, 3, 0, 2, 0, 4, 1, 6, 1, 1, 1, 3, 1, 1, 2, 2, 2, 0, 2, 1, 1, 1, 1, 2, 0, 0, 1, 1, 2, 0, 0, 1, 2, 2, 1, 1, 1, 0, 1, 1, 0, 0, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 7, 2, 2, 3, 3, 1, 2, 3, 2, 3, 0, 2, 1, 1, 2, 1, 1, 1, 2, 0, 2, 0, 1, 2, 0, 0, 2, 0, 2, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 1, 2, 1, 1, 3, 2, 2, 0, 2, 0, 0, 2, 1, 1, 2, 0, 0, 3, 2, 0, 1, 0, 1, 1, 1, 2, 1, 1, 1, 0, 1, 0, 2, 1, 1, 0, 0, 1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 2, 3, 2, 2, 0, 2, 0, 2, 0, 1, 0, 2, 1, 0, 2, 0, 0, 1, 0, 0, 4, 0, 1, 1, 2, 3, 2, 1, 2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 1, 2, 2, 2, 1, 1, 0, 2, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 0, 0, 1, 2, 0, 1, 2, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 1, 3, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 3, 0, 1, 1, 1, 1, 2, 0, 0, 1, 0, 0, 1, 2, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 1, 0, 1, 2, 6, 3, 3, 8, 3, 0, 3, 4, 3, 4, 0, 2, 0, 4, 1, 3, 1, 3, 1, 0, 1, 1, 1, 1, 0, 0, 1, 2, 3, 1, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
            ]
        },
        "Population": {
            "Units": "",
            "Data": [
                [1908, 1908, 1905, 1905, 1904, 1900, 1899, 1897, 1896, 1895, 1894, 1894, 1893, 1892, 1892, 1891, 1890, 1890, 1888, 1888, 1886, 1886, 1886, 1885, 1884, 1884, 1884, 1883, 1881, 1881, 1881, 1881, 1881, 1881, 1881, 1880, 1878, 1877, 1876, 1876, 1875, 1874, 1871, 1870, 1867, 1866, 1865, 1864, 1863, 1863, 1863, 1861, 1861, 1861, 1861, 1861, 1859, 1859, 1859, 1859, 1859, 1858, 1857, 1855, 1855, 1853, 1852, 1852, 1852, 1851, 1851, 1850, 1849, 1849, 1848, 1848, 1847, 1846, 1846, 1846, 1846, 1845, 1844, 1842, 1842, 1841, 1840, 1838, 1836, 1835, 1832, 1830, 1827, 1826, 1826, 1826, 1825, 1825, 1823, 1821, 1821, 1820, 1820, 1819, 1819, 1818, 1818, 1818, 1817, 1816, 1816, 1815, 1815, 1813, 1811, 1811, 1811, 1811, 1810, 1810, 1809, 1807, 1805, 1803, 1803, 1803, 1799, 1797, 1794, 1794, 1792, 1792, 1792, 1791, 1790, 1789, 1787, 1787, 1786, 1786, 1786, 1785, 1784, 1783, 1782, 1779, 1777, 1776, 1775, 1774],
                [1592, 1591, 1592, 1592, 1592, 1596, 1596, 1597, 1597, 1598, 1599, 1597, 1598, 1598, 1597, 1598, 1599, 1599, 1601, 1600, 1601, 1600, 1599, 1599, 1600, 1600, 1599, 1600, 1602, 1602, 1602, 1602, 1601, 1599, 1599, 1599, 1601, 1601, 1601, 1600, 1601, 1602, 1604, 1604, 1607, 1607, 1608, 1607, 1606, 1606, 1605, 1607, 1607, 1605, 1605, 1605, 1605, 1604, 1604, 1602, 1599, 1599, 1599, 1601, 1600, 1600, 1601, 1600, 1598, 1598, 1597, 1597, 1597, 1596, 1595, 1593, 1592, 1593, 1592, 1591, 1591, 1590, 1591, 1592, 1592, 1592, 1593, 1594, 1596, 1597, 1598, 1598, 1601, 1602, 1602, 1601, 1602, 1601, 1602, 1604, 1603, 1604, 1603, 1603, 1603, 1602, 1601, 1600, 1600, 1600, 1597, 1598, 1597, 1598, 1599, 1598, 1598, 1598, 1598, 1597, 1598, 1599, 1599, 1600, 1599, 1595, 1599, 1601, 1604, 1602, 1604, 1604, 1602, 1602, 1602, 1602, 1603, 1601, 1602, 1602, 1602, 1602, 1602, 1602, 1602, 1605, 1606, 1606, 1605, 1605],
                [1252, 1252, 1254, 1252, 1252, 1252, 1253, 1253, 1254, 1254, 1253, 1255, 1253, 1253, 1253, 1253, 1253, 1253, 1252, 1251, 1252, 1252, 1253, 1252, 1252, 1252, 1253, 1253, 1253, 1253, 1252, 1252, 1253, 1254, 1253, 1253, 1251, 1250, 1251, 1252, 1250, 1248, 1248, 1247, 1247, 1248, 1247, 1247, 1247, 1247, 1248, 1247, 1246, 1248, 1248, 1248, 1249, 1250, 1250, 1252, 1254, 1253, 1254, 1254, 1255, 1256, 1255, 1256, 1258, 1259, 1260, 1261, 1262, 1262, 1264, 1266, 1268, 1268, 1269, 1269, 1269, 1271, 1269, 1269, 1269, 1270, 1270, 1270, 1269, 1268, 1270, 1272, 1272, 1272, 1272, 1273, 1273, 1272, 1273, 1271, 1271, 1271, 1272, 1272, 1272, 1273, 1271, 1270, 1271, 1272, 1275, 1275, 1274, 1274, 1274, 1272, 1271, 1271, 1271, 1271, 1271, 1271, 1271, 1272, 1273, 1277, 1276, 1276, 1274, 1276, 1275, 1275, 1277, 1278, 1279, 1279, 1278, 1280, 1278, 1277, 1276, 1277, 1278, 1279, 1280, 1279, 1280, 1280, 1282, 1282],
                [1034, 1035, 1034, 1036, 1035, 1034, 1034, 1033, 1033, 1031, 1032, 1032, 1034, 1033, 1034, 1034, 1034, 1033, 1033, 1035, 1035, 1035, 1034, 1035, 1035, 1035, 1034, 1033, 1031, 1031, 1032, 1032, 1031, 1032, 1033, 1034, 1036, 1038, 1036, 1035, 1037, 1039, 1039, 1041, 1041, 1041, 1042, 1044, 1046, 1046, 1046, 1047, 1048, 1048, 1048, 1046, 1046, 1046, 1046, 1046, 1047, 1049, 1049, 1049, 1049, 1049, 1050, 1050, 1050, 1050, 1049, 1048, 1048, 1049, 1049, 1049, 1047, 1047, 1047, 1047, 1045, 1045, 1047, 1048, 1048, 1047, 1047, 1046, 1047, 1047, 1047, 1046, 1045, 1045, 1044, 1044, 1044, 1046, 1045, 1047, 1048, 1048, 1048, 1049, 1049, 1049, 1052, 1053, 1053, 1053, 1053, 1052, 1052, 1051, 1051, 1054, 1054, 1054, 1054, 1055, 1054, 1055, 1056, 1056, 1054, 1053, 1052, 1052, 1054, 1054, 1052, 1050, 1049, 1048, 1048, 1049, 1051, 1051, 1053, 1053, 1054, 1053, 1053, 1051, 1050, 1051, 1051, 1051, 1050, 1051],
                [793, 793, 794, 794, 796, 796, 796, 798, 798, 800, 799, 797, 797, 798, 798, 798, 798, 799, 800, 800, 800, 800, 801, 801, 801, 800, 801, 802, 804, 803, 802, 801, 802, 802, 802, 802, 801, 800, 802, 802, 802, 802, 800, 800, 800, 799, 799, 799, 799, 799, 798, 798, 797, 796, 796, 798, 799, 799, 798, 798, 798, 798, 797, 797, 797, 798, 797, 797, 797, 797, 798, 799, 799, 798, 798, 797, 798, 798, 797, 798, 800, 800, 800, 800, 800, 799, 799, 801, 801, 800, 800, 801, 801, 801, 802, 802, 801, 800, 801, 801, 799, 799, 798, 798, 797, 798, 797, 798, 798, 798, 797, 798, 800, 802, 803, 803, 803, 803, 804, 804, 805, 805, 805, 805, 806, 807, 807, 807, 807, 807, 810, 812, 813, 813, 813, 813, 813, 812, 812, 813, 813, 814, 813, 815, 815, 815, 815, 816, 817, 817],
                [665, 665, 665, 665, 662, 663, 663, 663, 663, 662, 663, 664, 664, 664, 664, 664, 664, 662, 662, 662, 662, 662, 661, 661, 660, 661, 661, 661, 660, 661, 661, 661, 661, 661, 661, 661, 661, 661, 661, 662, 661, 661, 664, 664, 664, 665, 665, 665, 664, 663, 664, 664, 665, 666, 666, 666, 666, 666, 667, 667, 666, 666, 666, 666, 666, 666, 666, 665, 665, 665, 665, 665, 665, 665, 665, 666, 667, 667, 667, 667, 667, 667, 667, 667, 667, 669, 669, 668, 668, 670, 670, 669, 669, 668, 668, 667, 668, 667, 666, 666, 668, 668, 669, 669, 670, 670, 671, 670, 669, 669, 669, 669, 669, 669, 669, 668, 667, 666, 666, 664, 664, 662, 663, 662, 663, 661, 662, 661, 661, 661, 661, 661, 661, 662, 662, 662, 662, 662, 662, 662, 662, 662, 663, 663, 663, 663, 663, 663, 662, 662],
                [567, 567, 565, 565, 568, 567, 567, 567, 567, 567, 566, 565, 565, 566, 565, 565, 565, 566, 566, 566, 566, 567, 568, 568, 569, 567, 566, 566, 567, 567, 568, 569, 569, 569, 569, 569, 570, 571, 571, 571, 572, 572, 572, 572, 572, 570, 570, 570, 571, 572, 572, 571, 571, 570, 570, 570, 570, 569, 568, 568, 569, 569, 569, 569, 569, 569, 569, 569, 568, 568, 568, 568, 568, 569, 569, 569, 568, 567, 568, 568, 567, 567, 567, 566, 566, 565, 565, 564, 564, 564, 564, 564, 565, 566, 566, 567, 567, 569, 570, 570, 569, 569, 568, 568, 567, 567, 566, 567, 567, 567, 567, 567, 567, 567, 567, 568, 570, 571, 571, 573, 573, 575, 575, 576, 576, 578, 578, 579, 577, 577, 577, 577, 577, 576, 574, 573, 573, 574, 573, 573, 573, 573, 573, 573, 574, 574, 573, 573, 574, 574],
                [398, 398, 400, 399, 399, 399, 399, 399, 399, 400, 401, 402, 402, 402, 403, 402, 402, 403, 403, 403, 403, 403, 403, 404, 404, 406, 407, 407, 407, 407, 407, 407, 407, 407, 407, 406, 406, 406, 406, 406, 406, 405, 403, 403, 403, 405, 404, 404, 403, 403, 403, 404, 403, 404, 404, 404, 403, 403, 404, 404, 404, 404, 405, 405, 405, 405, 405, 406, 407, 406, 405, 405, 405, 405, 405, 404, 405, 406, 406, 406, 407, 407, 407, 408, 408, 409, 409, 411, 411, 411, 411, 411, 411, 410, 410, 410, 409, 409, 409, 408, 409, 409, 410, 410, 411, 411, 412, 412, 413, 413, 414, 413, 413, 413, 413, 413, 413, 412, 412, 412, 411, 410, 410, 410, 410, 408, 409, 409, 411, 411, 410, 410, 410, 410, 412, 412, 411, 411, 411, 411, 411, 411, 411, 411, 411, 411, 412, 412, 412, 412],
                [349, 349, 349, 350, 350, 351, 351, 351, 350, 350, 350, 351, 351, 350, 350, 351, 351, 351, 351, 351, 350, 350, 350, 350, 350, 349, 349, 349, 349, 349, 349, 349, 349, 349, 349, 350, 350, 350, 349, 349, 349, 350, 351, 351, 351, 350, 351, 351, 352, 352, 352, 351, 352, 352, 352, 351, 352, 353, 352, 352, 352, 352, 352, 352, 352, 352, 353, 353, 353, 354, 355, 355, 354, 354, 354, 355, 355, 355, 355, 355, 355, 355, 355, 355, 354, 354, 353, 353, 353, 353, 353, 353, 353, 354, 354, 354, 355, 355, 355, 356, 356, 356, 356, 356, 356, 356, 355, 355, 354, 354, 354, 355, 355, 355, 355, 354, 354, 355, 355, 355, 356, 357, 357, 357, 357, 359, 359, 359, 359, 358, 359, 359, 359, 360, 360, 361, 362, 362, 363, 363, 363, 361, 361, 360, 359, 359, 359, 359, 359, 359],
                [281, 281, 281, 281, 281, 281, 280, 280, 281, 281, 281, 281, 281, 282, 282, 282, 282, 282, 282, 282, 283, 283, 282, 282, 282, 283, 283, 283, 283, 283, 283, 283, 283, 283, 283, 282, 281, 281, 282, 282, 281, 281, 282, 282, 282, 283, 283, 283, 283, 283, 283, 284, 284, 284, 284, 285, 285, 285, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 286, 287, 287, 287, 287, 286, 286, 286, 286, 285, 285, 285, 285, 285, 285, 286, 286, 286, 286, 286, 287, 287, 287, 287, 287, 287, 287, 287, 287, 286, 286, 286, 285, 285, 285, 285, 285, 286, 284, 284, 284, 284, 283, 282, 283, 283, 283, 283, 283, 283, 282, 282, 282, 282, 282, 282, 282, 281, 282, 282, 282, 282, 282, 282, 281, 281, 281, 281, 281, 281, 283, 283, 283, 284, 283, 283, 282, 282, 282],
                [218, 218, 218, 218, 218, 218, 219, 219, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 218, 219, 219, 219, 219, 219, 219, 219, 219, 218, 216, 216, 215, 215, 215, 215, 214, 214, 214, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 214, 214, 214, 214, 214, 214, 214, 214, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 213, 214, 214, 214, 214, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 215, 216, 216, 216, 217, 217, 216, 218, 218, 218, 218, 219, 220, 220, 220, 220, 220, 220, 220, 221, 221, 221, 221, 221, 220, 220, 221, 221, 220, 220, 220, 220, 220, 221, 221, 221, 221, 221, 221, 221, 221, 222, 222, 223, 223, 224, 224, 224],
                [188, 188, 188, 188, 188, 188, 188, 188, 189, 189, 188, 188, 188, 188, 188, 187, 187, 187, 187, 186, 186, 184, 182, 182, 182, 182, 182, 182, 181, 181, 182, 184, 184, 185, 185, 186, 187, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 189, 189, 189, 188, 188, 188, 188, 187, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 188, 187, 187, 187, 187, 187, 187, 187, 187, 187, 187, 186, 186, 186, 187, 186, 186, 186, 186, 186, 185, 184, 184, 184, 184, 184, 184, 184, 183, 183, 184, 184, 184, 184, 184, 184, 184, 184, 185, 185, 185, 185, 185, 185, 185, 185, 184, 184, 184, 184, 184, 184, 184, 184, 184, 184, 185, 185, 185, 185, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186, 186],
                [158, 158, 158, 158, 158, 158, 158, 158, 158, 158, 159, 159, 159, 159, 159, 160, 160, 160, 160, 161, 161, 163, 165, 165, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 165, 164, 164, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 167, 167, 167, 167, 167, 167, 167, 167, 167, 167, 168, 168, 168, 168, 169, 169, 169, 169, 169, 170, 171, 171, 171, 171, 171, 171, 171, 170, 170, 170, 170, 168, 168, 168, 168, 168, 168, 168, 167, 166, 166, 165, 165, 165, 165, 166, 166, 166, 166, 166, 166, 166, 166, 166, 166, 165, 165, 165, 165, 165, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 164, 163, 163, 163, 163, 163, 163, 163],
                [115, 115, 115, 114, 114, 114, 114, 114, 114, 114, 114, 114, 113, 113, 113, 113, 112, 112, 112, 111, 111, 111, 111, 111, 111, 111, 110, 110, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 110, 110, 110, 110, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 109, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 110, 109, 109, 109, 109, 109, 109, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 108, 107, 107, 107, 107, 107, 107, 107, 107, 107, 107, 106, 106, 106, 106, 108, 108, 108, 108, 110, 109, 109, 109, 109, 109, 109, 110, 111, 111, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 112, 113, 113, 113, 113, 113, 114, 113, 113, 113, 113, 113, 113, 113, 113, 113, 113, 113, 114, 114, 114, 114, 114, 114, 114],
                [95, 95, 95, 96, 96, 96, 96, 96, 96, 96, 96, 96, 97, 97, 97, 97, 98, 98, 98, 99, 99, 99, 99, 99, 99, 99, 100, 100, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 101, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 102, 103, 103, 103, 103, 103, 103, 104, 104, 104, 104, 104, 104, 103, 103, 103, 103, 103, 103, 103, 104, 104, 104, 103, 103, 103, 103, 103, 103, 103, 104, 104, 104, 104, 104, 104, 104, 104, 104, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 104, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105, 105],
                [78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 78, 77, 77, 77, 77, 77, 77, 77, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 75, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 76, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 74, 75, 75, 75, 75, 75, 75, 75, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74],
                [72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 72, 71, 71, 71, 71, 71, 71, 71, 72, 72, 72, 72, 72, 72, 72, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 72, 72, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 75, 75, 75, 75, 75, 75, 75, 75, 75, 75, 74, 74, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 73, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74, 74],
                [49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 49, 50, 50, 51, 51, 51, 52, 52, 52, 52, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 51, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 50],
                [39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 39, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 41, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 42, 43, 43, 43, 43, 43, 43, 43, 43, 43, 42, 42, 42, 42, 42],
                [30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 29, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 29, 29, 29, 29, 29],
                [119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 119, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 120, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121, 121]
            ]
        }
    }
}
HIV additional headers

When running HIV simulations, the header section contains the following additional parameters.

Parameter

Data type

Description

Base_Year

float

The absolute time in years when the simulation begins.
HIV channels

When running HIV simulations, the binned report contains the following channels.

Channel

Description

Infected

The number of individuals who are currently infected in that age bin on that day.

New Infections

The number of individuals who became infected on that day in that age bin.

Population

The total number of individuals in that age bin on that day.
HIV example

The following is an example of an HIV-specific BinnedReport.json file.

{
    "Header": {
        "DateTime": "Tue Mar 21 13:46:06 2023",
        "DTK_Version": "Malaria-Ongoing (bb265ad) Dec 21 2020 11:15:31",
        "Report_Version": "2.1",
        "Timesteps": 10,
        "Base_Year": 1995,
        "Subchannel_Metadata": {
            "AxisLabels": [ [ "Age" ] ],
            "NumBinsPerAxis": [ [ 21 ] ],
            "ValuesPerAxis": [
                [
                    [
                         1825,  3650,  5475,  7300,  9125,
                        10950, 12775, 14600, 16425, 18250,
                        20075, 21900, 23725, 25550, 27375,
                        29200, 31025, 32850, 34675, 36500,
                        999999
                    ]
                ]
            ],
            "MeaningPerAxis": [
                [
                    [    "<5",   "5-9", "10-14", "15-19", "20-24",
                      "25-29", "30-34", "35-39", "40-44", "45-49",
                      "50-54", "55-59", "60-64", "65-69", "70-74",
                      "75-79", "80-84", "85-89", "90-94", "95-99",
                      ">100"
                    ]
                ]
            ]
        },
        "Channels": 3
    },
    "Channels": {
        "Infected": {
            "Units": "",
            "Data": [
                [0, 15, 15, 15, 15, 15, 15, 15, 15, 15],
                [0, 10, 10, 10, 10, 10, 10, 10, 10, 10],
                [0, 15, 15, 15, 15, 15, 15, 15, 15, 15],
                [0,  7,  7,  7,  7,  7,  7,  7,  7,  7],
                [0,  4,  4,  4,  4,  4,  4,  4,  4,  4],
                [0,  7,  7,  7,  7,  7,  7,  7,  7,  7],
                [0,  4,  4,  4,  4,  4,  4,  4,  4,  4],
                [0,  3,  3,  3,  3,  3,  3,  3,  3,  3],
                [0,  3,  3,  3,  3,  3,  3,  3,  3,  3],
                [0,  4,  4,  4,  4,  4,  4,  4,  4,  4],
                [0,  3,  3,  3,  3,  3,  3,  3,  3,  3],
                [0,  6,  6,  6,  6,  6,  6,  6,  6,  6],
                [0,  1,  1,  1,  1,  1,  1,  1,  1,  1],
                [0,  1,  1,  1,  1,  1,  1,  1,  1,  1],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [0,  1,  1,  1,  1,  1,  1,  1,  1,  1],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [0,  0,  0,  0,  0,  0,  0,  0,  0,  0]
            ]
        },
        "New Infections": {
            "Units": "",
            "Data": [
                [0, 15, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 10, 0, 0, 0, 0, 0, 0, 0, 0],
                [0, 15, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  7, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  4, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  7, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  4, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  3, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  3, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  4, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  3, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  6, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  1, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  1, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  1, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0],
                [0,  0, 0, 0, 0, 0, 0, 0, 0, 0]
            ]
        },
        "Population": {
            "Units": "",
            "Data": [
                [36, 36, 36, 36, 36, 36, 36, 36, 36, 36],
                [17, 17, 17, 17, 17, 17, 17, 17, 17, 17],
                [20, 20, 20, 20, 20, 20, 20, 20, 20, 20],
                [18, 18, 18, 18, 18, 18, 18, 18, 18, 18],
                [11, 11, 11, 11, 11, 11, 11, 11, 11, 11],
                [10, 10, 10, 10, 10, 10, 10, 10, 10, 10],
                [ 9,  9,  9,  9,  9,  9,  9,  9,  9,  9],
                [ 9,  9,  9,  9,  9,  9,  9,  9,  9,  9],
                [11, 11, 11, 11, 11, 11, 11, 11, 11, 11],
                [ 8,  8,  8,  8,  8,  8,  8,  8,  8,  8],
                [ 8,  8,  8,  8,  8,  8,  8,  8,  8,  8],
                [ 8,  8,  8,  8,  8,  8,  8,  8,  8,  8],
                [ 2,  2,  2,  2,  2,  2,  2,  2,  2,  2],
                [ 2,  2,  2,  2,  2,  2,  2,  2,  2,  2],
                [ 2,  2,  2,  2,  2,  2,  2,  2,  2,  2],
                [ 1,  1,  1,  1,  1,  1,  1,  1,  1,  1],
                [ 0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [ 1,  1,  1,  1,  1,  1,  1,  1,  1,  1],
                [ 0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [ 0,  0,  0,  0,  0,  0,  0,  0,  0,  0],
                [ 0,  0,  0,  0,  0,  0,  0,  0,  0,  0]
            ]
        }
    }
}
DemographicsSummary

The demographic summary output report (DemographicsSummary.json) is a JSON-formatted file with the demographic channel output results of the simulation, consisting of simulation-wide averages by time step. The format is identical to the inset chart output report, except the channels reflect demographic categories, such as gender ratio.

To generate the demographics summary report, set the Enable_Demographics_Reporting configuration parameter to 1. The BinnedReport will also be generated.

The file contains a header and a channels section.

Channels

The channels section contains the following parameters.

Parameter

Data type

Description

Average Age

integer

The average age of the Statistical Population at each time step. This takes the age of each agent and multiplies it by the agent’s Monte Carlo Weight, adds them together, then divides that sum by the Statistical Population.

Gender Ratio (fraction male)

integer

The fraction of the statistical population that is male at each time step. This takes the Monte Carlo weight of each male, adds them together, then divides by the statistical population.

New Births

integer

The statistical number of children born during each time step. This is the sum of the Monte Carlo weight of each newborn.

New Natural Deaths

integer

The statistical number of people that died from natural causes (i.e. not disease) during each time step. This is the sum of the Monte Carlo weights of each person that died.

Population Age X-Y

integer

The statistical population of the people whose age is greater than or equal to X and strictly less than Y+1. For example, if X=10 and Y=14, then if 10 <= age < 15, the person will be counted in that channel. This channel is the sum of the Monte Carlo weight of each person that qualifies for that channel. The set of channels is starts at 0-5 (i.e.<5) and increases every 5 years until the last bin is those people over 100.

Possible Mothers

integer

The total number of females in the population whose age is greater than 14 years and less than 45 years.

Pseudo-Population

integer

The number of actual human agents in the simulation on that day. This number times the Monte Carlo Weight (which is controlled by the configuration parameter Individual_Sampling_Type) should be the same value as in the Statistical Population channel.

Statistical Population

integer

The total number of individuals in the simulation on that day. The sum of the Population Age X-Y channels at each time step should sum to this channel at the corresponding time step.
Example

The following is a sample of a DemographicsSummary.json file.

{
    "Header": {
        "DateTime": "Mon Mar 16 07:45:10 2015",
        "DTK_Version": "4777 v2.0-HIV 2015/02/26 10:51:25",
        "Report_Type": "InsetChart",
        "Report_Version": "3.2",
        "Start_Time": 0,
        "Simulation_Timestep": 1,
        "Timesteps": 5,
        "Channels": 28
    },
    "Channels": {
        "Average Age": {
            "Units": "",
            "Data": [
                8592.415039063,
                8593.427734375,
                8594.439453125,
                8595.41796875,
                8596.412109375
            ]
        },
        "Gender Ratio (fraction male)": {
            "Units": "",
            "Data": [
                0.5350999832153,
                0.5350999832153,
                0.5350999832153,
                0.5350999832153,
                0.5350999832153
            ]
        },
        "New Births": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0
            ]
        },
        "New Natural Deaths": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0
            ]
        },
        "Population Age 10-14": {
            "Units": "",
            "Data": [
                1203,
                1204,
                1202,
                1203,
                1203
            ]
        },
        "Population Age 15-19": {
            "Units": "",
            "Data": [
                1056,
                1057,
                1059,
                1059,
                1059
            ]
        },
        "Population Age 20-24": {
            "Units": "",
            "Data": [
                810,
                810,
                810,
                809,
                809
            ]
        },
        "Population Age 25-29": {
            "Units": "",
            "Data": [
                732,
                732,
                732,
                732,
                732
            ]
        },
        "Population Age 30-34": {
            "Units": "",
            "Data": [
                540,
                539,
                539,
                539,
                539
            ]
        },
        "Population Age 35-39": {
            "Units": "",
            "Data": [
                410,
                411,
                411,
                411,
                411
            ]
        },
        "Population Age 40-44": {
            "Units": "",
            "Data": [
                351,
                351,
                351,
                352,
                352
            ]
        },
        "Population Age 45-49": {
            "Units": "",
            "Data": [
                294,
                294,
                294,
                294,
                294
            ]
        },
        "Population Age 5-9": {
            "Units": "",
            "Data": [
                1599,
                1597,
                1598,
                1597,
                1599
            ]
        },
        "Population Age 50-54": {
            "Units": "",
            "Data": [
                201,
                201,
                201,
                201,
                201
            ]
        },
        "Population Age 55-59": {
            "Units": "",
            "Data": [
                194,
                194,
                194,
                193,
                193
            ]
        },
        "Population Age 60-64": {
            "Units": "",
            "Data": [
                163,
                163,
                163,
                164,
                164
            ]
        },
        "Population Age 65-69": {
            "Units": "",
            "Data": [
                111,
                111,
                111,
                111,
                111
            ]
        },
        "Population Age 70-74": {
            "Units": "",
            "Data": [
                104,
                104,
                104,
                103,
                103
            ]
        },
        "Population Age 75-79": {
            "Units": "",
            "Data": [
                86,
                86,
                86,
                87,
                87
            ]
        },
        "Population Age 80-84": {
            "Units": "",
            "Data": [
                55,
                55,
                55,
                55,
                55
            ]
        },
        "Population Age 85-89": {
            "Units": "",
            "Data": [
                61,
                61,
                61,
                61,
                61
            ]
        },
        "Population Age 90-94": {
            "Units": "",
            "Data": [
                49,
                49,
                49,
                49,
                49
            ]
        },
        "Population Age 95-99": {
            "Units": "",
            "Data": [
                30,
                30,
                30,
                30,
                30
            ]
        },
        "Population Age <5": {
            "Units": "",
            "Data": [
                1829,
                1829,
                1828,
                1828,
                1826
            ]
        },
        "Population Age >100": {
            "Units": "",
            "Data": [
                122,
                122,
                122,
                122,
                122
            ]
        },
        "Possible Mothers": {
            "Units": "",
            "Data": [
                1912,
                1912,
                1912,
                1913,
                1913
            ]
        },
        "Pseudo-Population": {
            "Units": "",
            "Data": [
                10000,
                10000,
                10000,
                10000,
                10000
            ]
        },
        "Statistical Population": {
            "Units": "",
            "Data": [
                10000,
                10000,
                10000,
                10000,
                10000
            ]
        }
    }
}
InsetChart

The inset chart (InsetChart.json) is an output report that is automatically generated with every simulation. It contains simulation-wide averages, one per time step, for a wide number of data channels. The channels are fully specified by the simulation type and cannot be altered without making changes to the EMOD source code. Python or other tools can be used to create charts out of the information contained in the file (see the example charts provided at the end of this page.)

Configuration

To generate the report, the following parameters must be configured in the config.json file:

Parameter

Data type

Min

Max

Default

Description

Enable_Default_Reporting

boolean

NA

NA

1

Set this to 1 (default value) to generate the report.

Report_HIV_Event_Channels_List

array of strings

NA

NA

[]

The list of events to be included in the report. For each event specified with this parameter, one channel will be added to the report. See Event list for possible values. If no events are listed, a ‘Number of Events’ channel will be included on the report and display the total number of all events that occurred during the simulation.

Inset_Chart_Include_Coital_Acts

boolean

NA

NA

0

When set to 1, the report will include channels about the number of coital acts per relationship type per day—in total, and those using condoms (eight channels added).

Inset_Chart_Has_Interventions

array of strings

NA

NA

[]

A list of interventions to be included in the report. For each intervention listed, one channel is added to the report showing the fraction of the population that has that intervention at that time step. Note: the values specified here must match the Intervention_Name parameters listed in the campaign.json file. See Individual-level interventions for information on configuring these parameters.

Inset_Chart_Has_IP

array of strings

NA

NA

[]

A list of individual property (IP) keys to be included in the report. For each value of each IP key provided, one channel is added to the report showing the fraction of the population with that Key:Value pair, at that time step (for example, the fractions in Risk:LOW, Risk:MEDIUM, and Risk:HIGH). See Individual and node properties for additional information on configuring IPs.

Inset_Chart_Include_Pregnancies

boolean

NA

NA

0

If set to 1, three channels are included in the report showing counts of new pregnancies, current pregnancies, and possible mothers at each time step.

 
{
    "Enable_Default_Reporting": 1,
    "Report_HIV_Event_Channels_List": ["NewInfectionEvent", "HIVNeedsHIVTest", "HIVPositiveHIVTest"],
    "Inset_Chart_Coital_Acts": 1,
    "Inset_Chart_Has_Interventions": ["PrEP"],
    "Inset_Chart_Has_IP": ["InterventionStatus"],
    "Inset_Chart_Include_Pregnancies": 1
}
Output file data
Headers

When running HIV simulations, the header section will contain the following parameters.

Parameter

Data type

Description

DateTime

string

The time stamp indicating when the report was generated.

DTK_Version

string

The version of EMOD used.

Report_Type

string

The type of output report.

Report_Version

string

The format version of the report.

Start_Time

integer

The time in days when the simulation begins.

Simulation_Timestep

integer

The number of days in each time step.

Timesteps

integer

The number of time steps in the simulation.

Channels

integer

The number of channels in the simulation.

Base_Year

float

The absolute time in years when the simulation begins. Determined by the Base_Year parameter in the config.json file.
Channels

When running HIV simulations, the following channels are included in the InsetChart.json file. For channels related to the HIV stage (latent, acute, AIDS), these definitions are described in more detail in Intrahost dynamics and HIV biology.

Channel

Description

Active COMMERCIAL Relationships

The current number of commercial relationships. See Relationships and contact networks for more information on relationship types.

Active INFORMAL Relationships

The current number of informal relationships.

Active MARITAL Relationships

The current number of marital relationships.

Active TRANSITORY Relationships

The current number of transitory relationships.

Births

The live births cumulative up to that day.

Campaign Cost

The cost of campaigns cumulative up to that day (set by the Cost_To_Consumer parameter).

Coital Acts Using Condoms-COMMERCIAL

Average number of coital acts using condoms per commercial relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-INFORMAL

Average number of coital acts using condoms per informal relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-MARITAL

Average number of coital acts using condoms per marital relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-TRANSITORY

Average number of coital acts using condoms per transitory relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-COMMERCIAL

Average number of coital acts per commercial relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-INFORMAL

Average number of coital acts per informal relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-MARITAL

Average number of coital acts per marital relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-TRANSITORY

Average number of coital acts per transitory relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Disease Deaths

The number of individuals whose death is attributed to HIV/AIDS, cumulative up to that day.

Fraction of New Infections From Rels Outside PFA

The fraction of the total new infections that occurred in relationships created via the StartNewRelationship intervention, rather than the Pair Forming Algorithm (PFA).

Infected

The fraction of the population currently infected.

New Infections

The number of individuals that got infected on that day.

Newly Symptomatic

The number individuals that became symptomatic on that day.

Num Rels Outside PFA

The count of relationships that were created via the StartNewRelationship intervention, rather than the Pair Forming Algorithm (PFA).

Number of (treated) Individuals with AIDS

The number of people who have AIDS but are on ART.

Number of (untreated) Individuals with AIDS

The number of individuals not on ART with AIDS.

Number of (untreated) Individuals with Acute HIV

The number of individuals not on ART with acute HIV.

Number of (untreated) Individuals with Latent HIV

The number of individuals not on ART with latent HIV.

Number of ART dropouts (cumulative)

The number of individuals who started and dropped ART, cumulative up to that day.

Number of Circumcised Males

The number of male individuals that are circumcised via the MaleCircumcision intervention.

Number of Events

The total number of events (births, new infections, etc.) cumulative up to that day.

Number of Individuals Ever in a Relationship

The number of individuals who have ever been in a relationship cumulative up to that day.

Number of Individuals HIV+ w/ CD4 < 200 (non-ART)

The number of individuals who are HIV+ with CD4 count less than 200 and NOT on ART on that day.

Number of Individuals HIV+ w/ CD4 < 200 (on-ART)

The number of individuals who are HIV+ with CD4 count less than 200 and ON ART on that day.

Number of Individuals HIV+ w/ CD4 >= 200 (non-ART)

The number of individuals who are HIV+ with CD4 count greater than 200 and NOT on ART on that day.

Number of Individuals HIV+ w/ CD4 >= 200 (on-ART)

The number of individuals who are HIV+ with CD4 count greater than 200 and ON ART on that day.

Number of Individuals on ART

The total number of individuals on ART on that day.

Paired People

The number of individuals currently in any type of relationship.

Post-Debut Population

The number of individuals that are sexually active.

Prevalence (Females, 15-49)

The fraction of infected individuals in the population of females 15-49.

Prevalence (Males, 15-49)

The fraction of infected individuals in the population of males 15-49.

Prevalence among Sexually Active

The fraction of infected individuals in the post-debut adult population.

Single Post-Debut Men

The number of sexually active males who are currently not in a relationship.

Single Post-Debut Women

The number of sexually active females who are currently not in a relationship.

Statistical Population

The total number of individuals in the simulation on that day.

Symptomatic Population

The total number of symptomatic HIV+ individuals.

Number of Events

If no events are listed in the Report_HIV_Event_Channels_List parameter, this channel will appear in the report, showing the total count of all events that occurred at each time step.

<Event Name>

For each even name listed in the Report_HIV_Event_Channels_List parameter, there will be a corresponding <Event Name> channel in the report, showing the count of those events at each time step. The Number of Events channel will no longer be included in the report.

Has_<Intervention Name>

For each intervention name listed in the Inset_Chart_Has_Interventions parameter, there will be a corresponding Has_<Intervention Name> channel in the report, showing counts of people that have at least one of the named interventions. Note: the intervention names in the list are not checked for accuracy; errors will result in all zeros being returned for that channel. Verify that each intervention name listed in this parameter is defined in the campaign file via the Intervention_Name parameter.

HasIP_<Key:Value>

For each IP key listed in the Inset_Chart_Has_IP parameter, corresponding HasIP_<Key:Value> channels will be added to the report, showing the fraction of people with that IP Key:Value pair, at that time step (one channel for each value of each IP Key). For a given IP, the fractions in each of its value channels should add up to one (1) at each time step.

Possible Mothers

Total number of women that could possibly be mothers (age is between 14 and 45) at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.

New Pregnancies

Total number of women that became pregnant at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.

Currently Pregnant

Total number of women that are currently pregnant at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.
Example

The following is an example of an HIV-specific InsetChart.json.

{
    "Header": {
        "DateTime": "Tue Feb 14 13:29:43 2023",
        "DTK_Version": "0 unknown-branch (unknown) Feb  3 2023 09:00:54",
        "Report_Type": "InsetChart",
        "Report_Version": "3.2",
        "Start_Time": 0,
        "Simulation_Timestep": 1,
        "Timesteps": 8,
        "Channels": 42,
        "Base_Year": 1995
    },
    "Channels": {
        "Active COMMERCIAL Relationships": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Active INFORMAL Relationships": {
            "Units": "Relationships",
            "Data": [4, 17, 27, 38, 43, 50, 57, 64]
        },
        "Active MARITAL Relationships": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Active TRANSITORY Relationships": {
            "Units": "Relationships",
            "Data": [3, 14, 35, 45, 48, 57, 65, 73]
        },
        "Births": {
            "Units": "Births",
            "Data": [1, 1, 2, 3, 4, 7, 9, 12]
        },
        "Campaign Cost": {
            "Units": "USD",
            "Data": [4, 4600, 11049, 11062, 11087, 11116, 11139, 11159]
        },
        "Coital Acts Using Condoms-COMMERCIAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts Using Condoms-INFORMAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0.0588235296309, 0, 0.0526315793395, 0.02325581386685, 0.0599999986589, 0.1228070184588, 0.109375]
        },
        "Coital Acts Using Condoms-MARITAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts Using Condoms-TRANSITORY": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0.3333333432674, 0.1428571492434, 0.0857142880559, 0.02222222276032, 0.02083333395422, 0.0526315793395, 0.04615384712815, 0.01369863003492]
        },
        "Coital Acts-COMMERCIAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts-INFORMAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [1, 0.8235294222832, 0.629629611969, 0.5526315569878, 0.5348837375641, 0.5199999809265, 0.3508771955967, 0.421875]
        },
        "Coital Acts-MARITAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts-TRANSITORY": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [1, 0.9285714030266, 0.7428571581841, 0.4888888895512, 0.4583333432674, 0.5438596606255, 0.3692307770252, 0.424657523632]
        },
        "Disease Deaths": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 82]
        },
        "Fraction of New Infections From Rels Outside PFA": {
            "Units": "Fraction",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Infected": {
            "Units": "Infected",
            "Data": [0, 0.4988502562046, 0.4988501667976, 0.4988322257996, 0.4988143146038, 0.4988682568073, 0.4988504052162, 0.4988145828247]
        },
        "New Infections": {
            "Units": "",
            "Data": [0, 13884, 0, 0, 1, 1, 1, 1]
        },
        "Newly Symptomatic": {
            "Units": "",
            "Data": [0, 0, 2874, 2, 4, 6, 3, 4]
        },
        "Num Rels Outside PFA": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (treated) Individuals with AIDS": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (untreated) Individuals with AIDS": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (untreated) Individuals with Acute HIV": {
            "Units": "",
            "Data": [0, 13884, 13883, 13883, 13884, 13885, 13886, 13887]
        },
        "Number of (untreated) Individuals with Latent HIV": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of ART dropouts (cumulative)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Circumcised Males": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Events": {
            "Units": "",
            "Data": [2343, 46758, 11359, 2274, 2230, 2409, 2145, 2352]
        },
        "Number of Individuals Ever in a Relationship": {
            "Units": "",
            "Data": [14, 62, 126, 174, 204, 246, 286, 328]
        },
        "Number of Individuals HIV+ w/ CD4 < 200 (non-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 93, 119, 143, 164]
        },
        "Number of Individuals HIV+ w/ CD4 < 200 (on-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Individuals HIV+ w/ CD4 >= 200 (non-ART)": {
            "Units": "",
            "Data": [0, 13884, 13883, 13883, 13791, 13766, 13743, 13723]
        },
        "Number of Individuals HIV+ w/ CD4 >= 200 (on-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Individuals on ART": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Paired People": {
            "Units": "People",
            "Data": [14, 62, 124, 166, 182, 214, 244, 274]
        },
        "Post-Debut Population": {
            "Units": "",
            "Data": [15821, 15820, 15821, 15823, 15824, 15825, 15826, 15827]
        },
        "Prevalence (Females, 15-49)": {
            "Units": "",
            "Data": [0, 0.5059130787849, 0.5059130787849, 0.5057594776154, 0.5057594776154, 0.5057594776154, 0.5058372020721, 0.5057594776154]
        },
        "Prevalence (Males, 15-49)": {
            "Units": "",
            "Data": [0, 0.4944348633289, 0.4945916235447, 0.4945123791695, 0.4948275983334, 0.4946708381176, 0.4946725070477, 0.4947500526905]
        },
        "Prevalence among Sexually Active": {
            "Units": "",
            "Data": [0, 0.5322580933571, 0.5476190447807, 0.5114942789078, 0.504901945591, 0.4959349632263, 0.493007004261, 0.4908536672592]
        },
        "Single Post-Debut Men": {
            "Units": "People",
            "Data": [7642, 7618, 7588, 7568, 7561, 7545, 7530, 7515]
        },
        "Single Post-Debut Women": {
            "Units": "People",
            "Data": [8165, 8140, 8109, 8089, 8081, 8066, 8052, 8038]
        },
        "Statistical Population": {
            "Units": "Population",
            "Data": [27832, 27832, 27830, 27831, 27832, 27833, 27836, 27838]
        },
        "Symptomatic Population": {
            "Units": "",
            "Data": [0, 0, 2874, 2876, 2880, 2886, 2889, 2893]
        }
    }
}
_images/HIVInsetChart-Example.png

Example of plots created from HIV-specific InsetChart data

PropertyReport

The property output report (PropertyReport.json) is a JSON-formatted file with the channel output results of the simulation, defined by the groups set up using IndividualProperties in the demographics file. See NodeProperties and IndividualProperties for more information. The report contains the count of individuals with each possible IP key-value combination. The < channel-title > tells you the statistic and property that are being counted. For example, it allows you to compare disease deaths for people in the high risk group versus the low risk group.

To generate the property report, set the Enable_Property_Output configuration parameter to 1.

The file contains a header and a channels section.

Channels

The channels section contains the following parameters.

Parameter

Data type

Description

<Channel_Title>

string

The title of the particular property channel. The channel titles use the following conventions: for a single property, <channel type>:<property>:<value>, and for multiple properties, <channel type>:<property 1>:<value>,<property 2>:<value>. For example, Infected:Accessibility:Easy or New Infections:Accessibility:Difficult,Risk:High.

Units

string

The units used for this channel.

Data

array

A list of the channel data at each time step.
Channel_Title

The following information is available for the <Channel_Title> parameters. Note that these channels will have separate sections for each IndividualProperites key:value pair.

Channel

Description

Disease Deaths

The number of people who died from an infection that day.

Infected

The number of people who have at least one infection on that day. These infections could be so new that they are not detectable via a diagnostic.

New Infections

The number of people with new infections that day.

Statistical Population

The total number of people in the simulation that day.
Example

The following is a sample of a PropertyReport.json file.

{
    "Header": {
        "DateTime": "Mon Feb 15 21:49:24 2016",
        "DTK_Version": "5538 trunk 2015/08/07 14:40:43",
        "Report_Type": "InsetChart",
        "Report_Version": "3.2",
        "Start_Time": 0,
        "Simulation_Timestep": 1,
        "Timesteps": 10,
        "Channels": 8
    },
    "Channels": {
        "Disease Deaths:Accessibility:Easy": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "Disease Deaths:Accessibility:Hard": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "Infected:Accessibility:Easy": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "Infected:Accessibility:Hard": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "New Infections:Accessibility:Easy": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "New Infections:Accessibility:Hard": {
            "Units": "",
            "Data": [
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        },
        "Statistical Population:Accessibility:Easy": {
            "Units": "",
            "Data": [
                6946,
                6946,
                6946,
                6946,
                6946,
                6946,
                6946,
                6946,
                6946,
                6946
            ]
        },
        "Statistical Population:Accessibility:Hard": {
            "Units": "",
            "Data": [
                3054,
                3054,
                3054,
                3054,
                3054,
                3054,
                3054,
                3054,
                3054,
                3054
            ]
        }
    }
}
ReportEventCounter

The event counter report (ReportEventCounter.json) is a JSON-formatted file that keeps track of how many of each event types occurs during a time step. The report produced is similar to the InsetChart.json channel report, where there is one channel for each event defined in the configuration file (config.json). This report only counts events; a similar report, ReportEventRecorder, will provide information about the person at the time of the event.

Configuration

The following parameters need to be configured to generate the report:

Parameter name

Data type

Min

Max

Default

Description

Filename_Suffix

string

NA

NA

(empty string)

Augments the filename of the report. If multiple reports are being generated, this allows you to distinguish among the multiple reports.

Start_Day

float

0

3.40282e+38

0

The day of the simulation to start collecting data.

End_Day

float

0

3.40282e+38

3.40282e+38

The day of the simulation to stop collecting data.

Node_IDs_Of_Interest

array of integers

0

2.14748e+09

[]

Data will be collected for the nodes in this list. Empty list implies all nodes.

Min_Age_Years

float

0

9.3228e+35

0

Minimum age in years of people to collect data on.

Max_Age_Years

float

0

9.3228e+35

9.3228e+35

Maximum age in years of people to collect data on.

Must_Have_IP_Key_Value

string

NA

NA

(empty string)

A Key:Value pair that the individual must have in order to be included. Empty string means to not include IPs in the selection criteria.

Must_Have_Intervention

string

NA

NA

(empty string)

The name of the intervention that the person must have in order to be included. Empty string means to not include interventions in the selection criteria.

Event_Trigger_List

list of strings

NA

NA

NA

The list of event triggers for the events included in the report. There will be a channel in the report for each event.

 
{
    "Reports": [{
        "class": "ReportEventCounter",
        "Filename_Suffix": "Node1",
        "Start_Day": 365,
        "End_Day": 465,
        "Node_IDs_Of_Interest": [ 1 ],
        "Min_Age_Years": 5,
        "Max_Age_Years": 10,
        "Must_Have_IP_Key_Value": "Risk:HIGH",
        "Must_Have_Intervention": "SimpleVaccine",
        "Event_Trigger_List": [
            "NewInfectionEvent",
            "NewClinicalCase"
        ]
    }],
    "Use_Defaults": 1
}
Channels

The channels section contains the following parameters:

Parameter

Data type

Description

<Event Names>

string

The name of the event.

Data

array

An array of event counts where each entry is the number of events that occurred during the timestep.

Units

string

Empty string, but it is the ‘event count’.
Example

The following is an example of ReportEventCounter.json.

{
    "Header": {
        "Channels": 4,
        "DTK_Version": "4148 Malaria-Ongoing (bb265ad) May 16 2019 09:39:35",
        "DateTime": "Tue Mar 12 15:16:08 2019",
        "Report_Type": "InsetChart",
        "Report_Version": "3.2",
        "Simulation_Timestep": 1,
        "Start_Time": 0,
        "Timesteps": 3
    },
    "Channels": {
        "Births": {
            "Data": [
                0,
                1,
                1
            ],
            "Units": ""
        },
        "EveryUpdate": {
            "Data": [
                1000,
                1001,
                1002
            ],
            "Units": ""
        },
        "NewInfectionEvent": {
            "Data": [
                110,
                0,
                2
            ],
            "Units": ""
        },
        "NonDiseaseDeaths": {
            "Data": [
                0,
                0,
                0
            ],
            "Units": ""
        }
    }
}
ReportEventRecorder

The health events and interventions report (ReportEventRecorder.csv) provides information on each individual’s demographics and health status at the time of an event. Additionally, it is possible to see the value of specific IndividualProperties, as assigned in the demographics file (see NodeProperties and IndividualProperties for more information).

This report is highly customizable; see the Configuration section, below, for details and instructions. Disease-specific information and examples are provided at the end of page.

Configuration

To generate this report, the following parameters must be configured in the config.json file (applies to all simulation types):

Parameter name

Data type

Min

Max

Default

Description

Report_Event_Recorder

boolean

0

1

0

Set to 1 to generate the report.

Report_Event_Recorder_Events

array of strings

NA

NA

[]

The list of events to include or exclude in the output report, based on how Report_Event_Recorder_Ignore_Events_In_List is set. See Event list for a list of all possible built-in events. Custom_Individual_Events may also be included. Warning: If the list is empty and Report_Event_Recorder_Ignore_Events_In_List is set to 0, no events will be returned.

Report_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the events listed in Report_Event_Recorder_Events will be included in the output report. If set to true (1), only the events listed in Report_Event_Recorder_Events will be excluded, and all other events will be included. To return all events from the simulation, set this value to 1 and leave the the Report_Event_Recorder_Events array empty.

Report_Event_Recorder_Individual_Properties

array of strings

NA

NA

[]

An array of optional individual property (IP) keys to be added to the report. One column will be added for each IP Key listed, indicating the individual’s value for that IP Key at the time of the event. See Individual and node properties for details on setting individual properties.

Report_Event_Recorder_Start_Day

float

0

3.40282e+38

0

The day of the simulation to start collecting data.

Report_Event_Recorder_End_Day

float

0

3.40282e+38

3.40282e+38

The day of the simulation to stop collecting data.

Report_Event_Recorder_Node_IDs_Of_Interest

array of integers

0

2.14748e+09

[]

Data will be collected for the nodes in this list. Leave the array empty (default value) to collect data on all nodes.

Report_Event_Recorder_PropertyChange_IP_Key_Of_Interest

string

NA

NA

""

If the string is not empty, then the recorder will add the PropertyChange event to the list of events that the report is listening to. However, it will only record the events where the property changed the value of the given key.

Report_Event_Recorder_Min_Age_Years

float

0

9.3228e+35

0

Minimum age in years of people to collect data on.

Report_Event_Recorder_Max_Age_Years

float

0

9.3228e+35

9.3228e+35

Maximum age in years of people to collect data on.

Report_Event_Recorder_Must_Have_IP_Key_Value

string

NA

NA

""

An individual property (IP) Key:Value pair that an individual must have in order to be included in the report. Leave the string empty (default value) to not include IPs in the selection criteria. See Individual and node properties for more information.

Report_Event_Recorder_Must_Have_Intervention

string

NA

NA

""

The name of the intervention that the individual must have in order to be included in the report. Leave the string empty (default value) to not include interventions in the selection criteria. See Individual-level interventions for more information.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Events": [],
    "Report_Event_Recorder_Ignore_Events_In_List": 1,
    "Report_Event_Recorder_Individual_Properties": ["Risk"],
    "Report_Event_Recorder_Start_Day": 1,
    "Report_Event_Recorder_End_Day": 300,
    "Report_Event_Recorder_Node_IDs_Of_Interest": [ 1, 2, 3 ],
    "Report_Event_Recorder_PropertyChange_IP_Key_Of_Interest": "",
    "Report_Event_Recorder_Min_Age_Years": 20,
    "Report_Event_Recorder_Max_Age_Years": 60,
    "Report_Event_Recorder_Must_Have_IP_Key_Value": "Risk:HIGH",
    "Report_Event_Recorder_Must_Have_Intervention": "",
}
Output file data

The report contains the following data channels for all simulation types.

Data channel

Data type

Description

Time

float

The time of the event, in days.

Node_ID

integer

The identification number of the node.

Event_Name

string

The event being logged. If Report_Event_Recorder_Ignore_Events_In_List is set to 0, then the event name will be one of the ones listed under Report_Event_Recorder_Events. Otherwise, it will be the name of any other event that occurs and is not listed under Report_Event_Recorder_Events.

Individual_ID

integer

The individual’s unique identifying number

Age

integer

The age of the individual in units of days. Divide by 365 to obtain age in years.

Gender

character

The gender of the individual: “M” for male, or “F” for female.

Infected

boolean

Describes whether the individual is infected or not; 0 when not infected, 1 for infected.

Infectiousness

float

A value ranging from 0 to 1 that indicates how infectious an individual is, with 0 = not infectious and 1 = very infectious. HIV and malaria simulation types have specific definitions listed below.

<IP Key>

string

An additional column will be added to the report for each IP Key listed in Report_Event_Recorder_Individual_Properties. The values shown in each column will be the value for the indicated key, for that individual, at the time of the event.
HIV additional channels

When running HIV simulations, the report contains the following additional channels.

Data channel

Data type

Description

Year

float

The time of the event in units of calendar year, including fractions of years up to two decimal places.

Infectiousness

float

The probability of HIV transmission per coital act, including intrahost factors like disease stage and ART, but excluding condoms. (Channel is included in all simulations, but definition varies by disease.)

HasHIV

character

Indicates whether or not the individual is infected with HIV: “N” if not infected, “Y” if infected.

OnART

character

Indicates whether or not the individual is on ART: “N” if not on ART, “Y” if the individual is on ART.

CD4

float

The individual’s current CD4 count, regardless of when CD4 testing was performed.

WHO_Stage

float

The individual’s WHO stage, linearly interpolated between integer values. Round down to obtain the integer value for the WHO clinical stage. Uninfected individuals will be assigned a value of -1.

HIV_Stage

enum

Indicates the individual’s HIV stage. Possible values are: NOT_INFECTED, ACUTE, LATENT, AIDS, ON_ART.

InterventionStatus

string

The value of the individual’s InterventionStatus individual property at the time of the event. If InterventionStatus has not been configured, then the value will be “None.”
Example

The following is an example of a ReportEventRecorder.csv report from an HIV simulation:

Time

Year

Node_ID

Event_Name

Individual_ID

Age

Gender

Infected

Infectiousness

HasHIV

OnART

CD4

WHO_Stage

HIV_Stage

InterventionStatus

1

1995

1

NewlySymptomatic

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

None

1

1995

1

TestingOnSymptomatic1

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

TestingOnSymptomatic

1

1995

1

ARTStaging0

119

1114.49

M

1

0.026

Y

N

538.063

1.004

ACUTE

TestingOnSymptomatic

1

1995

1

NewlySymptomatic

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

None

1

1995

1

TestingOnSymptomatic1

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

TestingOnSymptomatic

1

1995

1

ARTStaging0

169

16666.3

F

1

0.026

Y

N

539.601

1.00142

ACUTE

TestingOnSymptomatic

2

1995.01

1

LinkingToART0

53

322.219

F

1

0.026

Y

N

527.811

1.03261

ACUTE

ARTStaging

2

1995.01

1

LinkingToART0

89

2525.18

F

1

0.026

Y

N

535.089

2.082

ACUTE

ARTStaging

2

1995.01

1

LinkingToART0

95

2329.52

M

1

0.026

Y

N

469.703

3.00982

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

2

3930.41

F

1

0.026

Y

N

510.138

1.05865

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

6

3333.92

F

1

0.026

Y

N

519.006

1.17656

ACUTE

ARTStaging

9

1995.02

1

LinkingToPreART0

21

1608.53

F

1

0.026

Y

N

476.802

1.11907

ACUTE

ARTStaging

15

1995.04

1

SixWeeksOld

40

42.2201

M

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

16

1995.04

1

OnPreART0

169

16681.3

F

1

0.026

Y

N

525.459

1.02264

ACUTE

LinkingToPreART

66

1995.18

1

TwelveWeeksPregnant

18

8926.42

F

1

0.026

Y

N

527.546

1.11365

ACUTE

None

66

1995.18

1

TestingOnANC1

18

8926.42

F

1

0.026

Y

N

527.546

1.11365

ACUTE

None

72

1995.2

1

ARTStaging0

18

8932.42

F

1

0.026

Y

N

526.372

1.12398

ACUTE

TestingOnANC

80

1995.22

1

LinkingToPreART0

18

8940.42

F

1

0.026

Y

N

524.808

1.13776

ACUTE

ARTStaging

81

1995.22

1

TwelveWeeksPregnant

125

9696.05

F

1

0.026

Y

N

511.301

1.12313

ACUTE

None

81

1995.22

1

TestingOnANC1

125

9696.05

F

1

0.026

Y

N

511.301

1.12313

ACUTE

None

87

1995.24

1

OnPreART0

18

8947.42

F

1

0.026

Y

N

523.442

1.14981

ACUTE

LinkingToPreART

92

1995.25

1

TwelveWeeksPregnant

30

6603.43

F

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

92

1995.25

1

TestingOnANC1

30

6603.43

F

0

0

N

N

1.00E+06

-1

NOT_INFECTED

None

96

1995.26

1

NewlySymptomatic

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

None

96

1995.26

1

TestingOnSymptomatic1

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

TestingOnSymptomatic

96

1995.26

1

ARTStaging0

117

20214.4

M

1

0.026

Y

N

482.367

1.29881

LATENT

TestingOnSymptomatic

104

1995.28

1

LinkingToPreART0

117

20222.4

M

1

0.026

Y

N

477.668

1.32371

LATENT

ARTStaging
ReportHumanMigrationTracking

The human migration tracking report (ReportHumanMigrationTracking.csv) is a CSV-formatted report that provides details about human travel during simulations. The finished report will provide one line for each surviving individual that migrates during the simulation.

Configuration

There are no special parameters that need to be configured to generate the report. However, the simulation must have migration enabled (see the migration parameters in Configuration parameters).

Report structure and channel descriptions

The file contains the following data channels:

Data channel

Data type

Description

Time

integer

The day that an individual leaves their current node.

IndividualID

integer

The ID of the migrating individual.

AgeYears

integer

The age (in years) of the migrating individual.

Gender

string

The gender of the individual. Possible values are M or F.

IsAdult

enum

Possible values are T or F; T (true) if individual’s age is greater than the configuration parameter Minimum_Adult_Age_Years.

Home_NodeID

string

The external ID of the node the individual considers to be their ‘home’ node.

From_NodeID

string

The external ID of the node the individual is moving from.

To_NodeID

string

the external ID of the node the individual is moving to.

MigrationType

enum

The type of migration that is occurring. When the event is SimulationEnd, the values are either ‘home’ or ‘away,’ indicating if the individual was in their home node or not when the simulation ended. Otherwise, possible values are air, local, sea, regional, local, family, or intervention.

Event

enum

Possible values are Emigrating, NonDiseaseDeaths, DiseaseDeaths, or SimulationEnd. Emigrating means the individual is moving, SimulationEnd means the simulation has finished.
Example

The following is an example of ReportHumanMigrationTracking.csv.

Time

IndividualID

AgeYears

Gender

IsAdult

Home_NodeID

From_NodeID

To_NodeID

MigrationType

Event

2

46

94.6986

F

T

1

1

4

local

Emigrating

4

108

35.7116

M

T

2

2

5

local

Emigrating

9

108

35.7253

M

T

2

5

2

regional

Emigrating

12

46

94.726

F

T

1

4

9

regional

Emigrating

13

46

94.7287

F

T

1

9

6

local

Emigrating

17

108

35.7472

M

T

2

2

5

local

Emigrating

22

46

94.7534

F

T

1

6

7

regional

Emigrating

23

108

35.7637

M

T

2

5

2

regional

Emigrating

25

108

35.7691

M

T

2

2

1

local

Emigrating

28

46

94.7698

F

T

1

7

4

local

Emigrating

35

46

94.789

F

T

1

4

7

regional

Emigrating

37

46

94.7945

F

T

1

7

4

local

Emigrating

44

46

94.8137

F

T

1

4

8

regional

Emigrating

100

1

38.9821

M

T

1

1

1

home

SimulationEnd

100

46

94.9643

F

T

1

8

8

regional

SimulationEnd

100

108

35.9719

M

T

2

1

1

local

SimulationEnd
ReportNodeDemographics

The node demographics report (ReportNodeDemographics.csv) is a CSV-formatted report that provides population information stratified by node. For each time step, the report will collect data on each node and age bin.

Configuration

To generate this report, the following parameters must be configured in the custom_reports.json file:

Parameter name

Data type

Min

Max

Default

Description

Age_Bins

array of floats

-3.04E+38

3.04E+38

[ ]

The age bins (in years, in ascending order) to aggregate within and report. An empty array does not stratify by age.

IP_Key_To_Collect

string

NA

NA

(empty string)

The name of the IndividualProperties (IP) key by which to stratify the report. An empty string means the report is not stratified by IP.

Stratify_By_Gender

boolean

NA

NA

1

Set to true (1) to stratify by gender; a value of 0 will not stratify by gender.

 
{
    "Reports": [
        {
            "class": "ReportNodeDemographics",
            "Age_Bins": [
                10,
                20,
                30,
                40,
                50,
                60,
                70,
                80,
                90,
                100,
                125
            ],
            "IP_Key_To_Collect": "",
            "Stratify_by_Gender": 1
        }
    ],
    "Use_Defaults": 1
}
Output file data

The report will contain the following output data, divided between stratification columns and data columns.

Stratification columns

Parameter

Data type

Description

Time

float

The day of the simulation that the data was collected.

NodeID

integer

The external ID of the node for the data in the row in the report.

Gender

enum

Possible values are M or F; the gender of the individuals in the row in the report. This column only appears if Stratify_By_Gender = 1.

AgeYears

float

The max age in years of the bin for the individuals in the row in the report. If Age_Bins is empty, this column does not appear.

IndividualProp

string

The value of the IP for the individuals in the row in the report. If IP_Key_To_Collect is an empty string, then this column does not appear.
Data columns

Parameter

Data type

Description

NumIndividuals

integer

The number of individuals that meet the stratification values.

NumInfected

integer

The number of infected individuals that meet the stratification values.

NodeProp = <Node Property Keys>

string

For each possible Node Property, there is one column where the data in the column is the value of that particular property. If there are no Node Properties, then there are no columns.
Example

The following is an example of ReportNodeDemographics.csv.

Time

NodeID

Gender

AgeYears

IndividualProp=Risk

NumIndividuals

NumInfected

0

2

M

40

High

1455

0

0

2

M

40

Low

627

0

0

2

M

125

High

47

0

0

2

M

125

Low

24

0

0

2

F

40

High

1390

0

0

2

F

40

Low

609

0

0

2

F

125

High

43

0

0

2

F

125

Low

22

0

0

1

M

40

High

459

0

0

1

M

40

Low

1630

0

0

1

M

125

High

18

0

0

1

M

125

Low

47

0

0

1

F

40

High

439

0

0

1

F

40

Low

1597

0

0

1

F

125

High

17

0

0

1

F

125

Low

67

0

1

2

M

40

High

1455

0

1

2

M

40

Low

627

0

1

2

M

125

High

47

0

1

2

M

125

Low

24

0

1

2

F

40

High

1390

0

1

2

F

40

Low

609

0

1

2

F

125

High

43

0

1

2

F

125

Low

22

0

1

1

M

40

High

459

0

1

1

M

40

Low

1630

26

1

1

M

125

High

18

0

1

1

M

125

Low

47

0

1

1

F

40

High

439

1

1

1

F

40

Low

1597

17

1

1

F

125

High

17

0

1

1

F

125

Low

67

0
SpatialReport

The spatial output report breaks the channel data down per node, rather than across the entire simulation. It is a set of binary files, consisting of one file per channel. For each value set in the Spatial_Output_Channels configuration parameter array, a binary file with the name convention SpatialReport_<channel>.bin is generated. In addition, Enable_Spatial_Output must be set to 1.

The binary format of the file consists of a stream of 4-byte integers followed by a stream of 4-byte floating point values. The first value is a 4-byte integer representing the number of nodes in the file and the second is a 4-byte integer that contains the number of time steps in the file. Following these two values is a stream of 4-byte integers that contain the node ID values in the order they will appear in the rest of the file. Following the node IDs is an array of 4-byte floating point values that represent the output values at the first time step for each node. The next array contains the values at the second time step, and so on.

The following diagram shows the format for data in the spatial output report file:

_images/spatialOutputBFF.jpg
Configuration

The following is an example of a spatial output channel configuration (config.json), and the following table defines the spatial output channels you can add to this report.

{
    "Enable_Spatial_Output": 1,
    "Spatial_Output_Channels": [
        "Population",
        "New_Infections",
        "Prevalence",
        "Births"
    ]
}
ReportHIVByAgeAndGender

The age- and gender-stratified HIV report (ReportHIVByAgeAndGender.csv) provides a detailed set of HIV-related statistics, with numerous ways to customize and stratify the output. The report format facilitates further analysis using a pivot table.

Some results, such as population size or number infected, are reported as single “snapshots” at the end of the reporting period. Other values, such as deaths or new infections, are aggregated for the entire reporting period. Further information on the output data types can be seen in the Output file data section.

See the Configuration section, below, for customization options and instructions.

Configuration

To generate this report, the following parameters must be configured in the config.json file:

Parameter

Data type

Min

Max

Default

Description

Report_HIV_ByAgeAndGender

boolean

NA

NA

0

Set to 1 to generate the report.

Report_HIV_ByAgeAndGender_Start_Year

float

1900

2200

1900

The simulation time in years to start collecting data.

Report_HIV_ByAgeAndGender_Stop_Year

float

1900

2200

2200

The simulation time in years to stop collecting data.

Report_HIV_ByAgeAndGender_Collect_Gender_Data

boolean

NA

NA

0

When set to 1, the output report will be stratified by gender.

Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data

array of floats

-3.40282e+38

3.40282e+38

[]

A list of bins used to stratify the report by age. Each value defines the minimum value (inclusive) of that bin, while the next value defines the maximum value (exclusive) of the bin. The values cannot be equal and must be listed in ascending order. Leave the array empty to not stratify the report by age. The maximum number of age bins is 100.

Report_HIV_ByAgeAndGender_Collect_Circumcision_Data

boolean

NA

NA

0

When set to 1, the IsCircumcised column is included in the output report. The report data will by stratified by those who do or do not have the MaleCircumcision intervention. Note: setting this to 1 doubles the number of rows in the output report.

Report_HIV_ByAgeAndGender_Collect_HIV_Data

boolean

NA

NA

0

When set to 1, the HasHIV column is included in the output report. The report data will stratified by those who do or do not have HIV. Cannot be used with Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data. Note: setting this to 1 doubles the number of rows in the output report.

Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data

boolean

NA

NA

0

When set to 1, the HIV_Stage column is included in the output report. The report data will be stratified by HIV Infection Stage (NOT_INFECTED, ACUTE, LATENT, AIDS, ON_ART). Cannot be used with Report_HIV_ByAgeAndGender_Collect_HIV_Data or Report_HIV_ByAgeAndGender_Collect_On_Art_Data.

Report_HIV_ByAgeAndGender_Collect_On_Art_Data

boolean

NA

NA

0

When set to 1, the On_Art_Dim column is included in the output report. The report data will be stratified by those individuals who are on ART and those who are not. Cannot be used with Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data. Note: setting this to 1 doubles the number of rows in the output report.

Report_HIV_ByAgeAndGender_Collect_IP_Data

array of strings

NA

NA

[]

A list of individual property (IP) keys used to stratify the report. A column will be added to the report for each IP listed. Specify the IP values by adding an IndividualProperties parameter in the demographics file. See Individual and node properties for details on setting individual properties. Note: each IP key included here will also increase the number of rows in the report by several fold (once for each possible IP Key:Value pair).

Report_HIV_ByAgeAndGender_Collect_Intervention_Data

array of strings

NA

NA

[]

A list of interventions used to stratify the report. This allows for reporting on a subset (or all) of the interventions that an individual has been on, of those listed in the Intervention_Name campaign parameter. Note: this can only be used with interventions that remain with an individual for a period of time, such as VMMC, vaccine/PrEP, or those with a delay state in the cascade of care. See Individual-level interventions for a list of possible interventions.

Report_HIV_ByAgeAndGender_Add_Transmitters

boolean

NA

NA

0

When set to 1, the Transmitters column is included in the output report. For a given row, this value indicates how many individuals that have transmitted the disease meet the specifications of that row.

Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4

boolean

NA

NA

0

When set to 1, the number of infected individuals will be segregated into four columns based on CD4 count. When set to 0, the number of infected individuals are aggregated into one column regardless of CD4 count. Note: this creates additional polling columns, not more stratification rows.

Report_HIV_ByAgeAndGender_Has_Intervention_With_Name

string

NA

NA

""

This parameter is being deprecated. Use Report_HIV_ByAgeAndGender_Collect_Intervention_Data instead. If an intervention is listed for this parameter, one column will be added to the report, indicating how many individuals in the row have the intervention. See Individual-level interventions for possible intervention values. Note: this only works for interventions that remain with an individual for a period of time, such as VMMC, vaccine/PrEP, or those with a delay state in the cascade of care.

Report_HIV_ByAgeAndGender_Event_Counter_List

array of strings

NA

NA

[]

A list of events used to stratify the report. A column will be added to the report for each event listed, showing the number of times the event occurred during the reporting period. To be counted, the individual must qualify for the row stratification at the time the event occurred, not necessarily at the end of the reporting period. See Event list for possible event values.

Report_HIV_ByAgeAndGender_Add_Relationships

boolean

NA

NA

0

When set to 1, the report will contain data on the population currently in a relationship and ever in a relationship for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL), eight columns total. Additionally, columns containing a sum of individuals in two or more partnerships (Has Concurrent Partners) and a sum of the lifetime number of relationships (Lifetime Partners) will be included.

Report_HIV_ByAgeAndGender_Add_Concordant_Relationships

boolean

NA

NA

0

When set to 1, a Concordant column for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL) is included in the output report. These contain totals for each relationship of each type where both partners have the same HIV status.

 
{
        "Report_HIV_ByAgeAndGender": 1,
        "Report_HIV_ByAgeAndGender_Start_Year": 2000,
        "Report_HIV_ByAgeAndGender_Stop_Year": 2050,
        "Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data": [ 15, 20, 25, 30, 35, 40, 125 ],
        "Report_HIV_ByAgeAndGender_Collect_Circumcision_Data": 0,
        "Report_HIV_ByAgeAndGender_Collect_Gender_Data": 1,
        "Report_HIV_ByAgeAndGender_Collect_HIV_Data": 1,
        "Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data": 0,
        "Report_HIV_ByAgeAndGender_Collect_IP_Data": ["InterventionStatus"],
        "Report_HIV_ByAgeAndGender_Collect_Intervention_Data": ["PrEP"],
        "Report_HIV_ByAgeAndGender_Collect_On_Art_Data": 1,
        "Report_HIV_ByAgeAndGender_Event_Counter_List": ["TestedNegative"],
        "Report_HIV_ByAgeAndGender_Has_Intervention_With_Name": "",
        "Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4": 1,
        "Report_HIV_ByAgeAndGender_Add_Concordant_Relationships": 1,
        "Report_HIV_ByAgeAndGender_Add_Relationships": 0,
        "Report_HIV_ByAgeAndGender_Add_Transmitters": 0,
}
Output file data

The output report has three types of columns: stratification, polling, and period. The Stratification columns have a predetermined value such as true (1) or false (0). The individuals in the row must have this attribute to be included. The Polling columns are those that count statistics as a snapshot at the end of the reporting period. That is, if HIV_Reporting_Period is set to 360, then at the end of every 180 days, the report will take a survey/poll to count statistics on the population. The data reflects the counts for that specific day. By contrast, the Period columns will contain counts for the entire reporting period, stratified into the rows the individuals qualify for when the count occurs. It is possible that an individual qualifies for one stratification when the count occurs, and another when the polling is done.

Data columns of each type are as follows.

Stratification columns

Data channel

Data type

Description

Year

float

The year at the end of the semiannual interval being recorded. For example, 1980.5 means that the counts in this row were aggregated over the first half of 1980, reported as a snapshot in the middle of the year 1980.

NodeId

integer

The numerical identifier of the node as defined in the demographics. See Demographics parameters for details on configuring the NodeID values.

Gender

boolean

The gender of the individual. 0 indicates male, 1 indicates female.

Age

float

The age of the individual, as configured by the Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data parameter.

IP_Key:<IP_Key>

string

For each IP key in the Report_HIV_ByAgeAndGender_Collect_IP_Data list, there will be a corresponding IP_Key column in the report. The individuals counted in that row will have that value for that key. See the Configuration section, above, for details on setting the Report_HIV_ByAgeAndGender_Collect_IP_Data values.

HasIntervention:<Intervention>

string

For each intervention name in the Report_HIV_ByAgeAndGender_Collect_Intervention_Data list, there will be a corresponding HasIntervention column in the report. Columns values will be 0 and 1, where 0 indicates that all individuals in that row do not have the intervention, and 1 indicates that they do. Note: The intervention names in the list are not checked for accuracy; errors will result in all zeros being returned for that column. Verify that each intervention name listed in this parameter is defined in the campaign file via the Intervention_Name parameter. The default of the Intervention_Name parameter is the class name of the intervention. See the Configuration section, above, for additional details on setting the Report_HIV_ByAgeAndGender_Collect_Intervention_Data values.

IsCircumcised

integer

If the Report_HIV_ByAgeAndGender_Collect_Circumcision_Data parameter is set to 1, then this column will be added to the report. The column values will be 0 or 1, where 0 indicates that all individuals in the row have not been circumcised, and 1 indicates that they have been.

HasHIV

integer

If the Report_HIV_ByAgeAndGender_Collect_HIV_Data parameter is set to 1, then this column will be added to the report. The column values will be 0 or 1, where 0 indicates that all individuals in that row are not infected with HIV, and 1 indicates they are.

HIV_Stage

enum

If the Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data parameter is set to 1, then this column will be added to the report. The values of the column will be NOT_INFECTED, ACUTE, LATENT, AIDS, and ON_ART, indicating the HIV stage of all individuals in that row.

On_Art_Dim

integer

If the Report_HIV_ByAgeAndGender_Collect_On_Art_Data parameter is set to 1, then this column will be added to the report. The values will be 0 or 1, where 0 indicates that all individuals in the row are not on ART, and 1 indicates they are.
Polling columns

Data channel

Data type

Description

Population

float

The total number of individuals that qualify for the stratification defined by the stratifying columns.

Infected

float

The number of HIV-infected individuals that qualify for the stratification defined by the stratifying columns.

On_ART

float

The number of individuals receiving ART that qualify for the stratification defined by the stratifying columns.

Tested Past Year or On_ART

float

The number of individuals receiving ART or having tested in the past year that qualify for the stratification defined by the stratifying columns.

Tested Ever

float

The number of individuals having ever been tested for HIV that qualify for the stratification defined by the stratifying columns.

Diagnosed

float

The number of HIV positive individuals. Equal to the number of new HIV positive diagnoses minus the number of individuals who died due to HIV.

Infected CD4 Under 200 (Not On ART)

float

If the Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4 parameter is set to 1, then this column will be added to the report. It indicates the number of individuals whose CD4 count is under 200 and who are not on ART.

Infected CD4 200 to 349 (Not On ART)

float

If the Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4 parameter is set to 1, then this column will be added to the report. It indicates the number of individuals whose CD4 count is between 200 and 349 and who are not on ART.

Infected CD4 350 to 499 (Not On ART)

float

If the Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4 parameter is set to 1, then this column will be added to the report. It indicates the number of individuals whose CD4 count is between 350 and 499 and who are not on ART.

Infected CD4 500 Plus (Not On ART)

float

If the Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4 parameter is set to 1, then this column will be added to the report. It indicates the number of individuals whose CD4 count is greater than or equal to 500 and who are not on ART.

HasIntervention(<Intervention>)

float

This parameter is being deprecated. Use Report_HIV_ByAgeAndGender_Collect_IP_Data instead; see Configuration for details. If a value is set for the Report_HIV_ByAgeAndGender_Has_Intervention_With_Name parameter, this column will be added to the report. It indicates the number of individuals in the row who have the specified intervention. Note: The intervention names in Report_HIV_ByAgeAndGender_Has_Intervention_With_Name are not checked for accuracy; errors will result in all zeros being returned for the column. Verify that the intervention name listed for this parameter is correct.

Currently (TRANSITORY)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that are in at least one transitory relationship at the end of the reporting period.

Currently (INFORMAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that are in at least one informal relationship at the end of the reporting period.

Currently (MARITAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that are in at least one marital relationship at the end of the reporting period.

Currently (COMMERCIAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that are in at least one commercial relationship at the end of the reporting period.

Ever (TRANSITORY)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that have had at least one transitory relationship during their lifetime.

Ever (INFORMAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that have had at least one informal relationship during their lifetime.

Ever (MARITAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that have had at least one marital relationship during their lifetime.

Ever (COMMERCIAL)

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row that have had at least one commercial relationship during their lifetime.

Has Concurrent Partners

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of individuals in the row who are in at least two relationships at the end of the reporting period.

Current Partners

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of partners for the individuals that qualify for the row. That is, if an individual qualifies for the row, this column will include the number of partners they have at the end of the reporting period.

Lifetime Partners

float

If the Report_HIV_ByAgeAndGender_Add_Relationships parameter is set to 1, then this column will be added to the report. It indicates the number of partners ever had by the individuals that qualify for the row. That is, if an individual that qualifies for the row has had 10 different partners during their life time at the end of the reporting period, then their 10 will be added to the value in the column.

Num_TRANSITORY

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of transitory relationships at the end of the reporting period for individuals that qualify for the row. If two people are in a transitory relationship with each other and they both qualify for the row, both are counted separately (two total).

Num_INFORMAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of informal relationships at the end of the reporting period for individuals that qualify for the row. If two people are in an informal relationship with each other and they both qualify for the row, both are counted separately (two total).

Num_MARITAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of marital relationships at the end of the reporting period for individuals that qualify for the row. If two people are in a marital relationship with each other and they both qualify for the row, both are counted separately (two total).

Num_COMMERCIAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of commercial relationships at the end of the reporting period for individuals that qualify for the row. If two people are in a commercial relationship with each other and they both qualify for the row, both are counted separately (two total).

Num_Concordant_TRANSITORY

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of transitory relationships at the end of the reporting period where both partners have the same HIV status. If the person qualifying for the row is HIV negative and has two relationships—one with partner that is also HIV negative and one with a partner that is HIV positive—only the relationship where they are both HIV negative is counted.

Num_Concordant_INFORMAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of informal relationships at the end of the reporting period where both partners have the same HIV status. If the person qualifying for the row is HIV negative and has two relationships—one with partner that is also HIV negative and one with a partner that is HIV positive—only the relationship where they are both HIV negative is counted.

Num_Concordant_MARITAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of marital relationships at the end of the reporting period where both partners have the same HIV status. If the person qualifying for the row is HIV negative and has two relationships—one with partner that is also HIV negative and one with a partner that is HIV positive—only the relationship where they are both HIV negative is counted.

Num_Concordant_COMMERCIAL

float

If the Report_HIV_ByAgeAndGender_Add_Concordant_Relationships parameter is set to 1, then this column will be added to the report. It indicates the total number of commercial relationships at the end of the reporting period where both partners have the same HIV status. If the person qualifying for the row is HIV negative and has two relationships—one with partner that is also HIV negative and one with a partner that is HIV positive—only the relationship where they are both HIV negative is counted.
Period columns

Data channel

Data type

Description

Newly Infected

float

The number of newly infected individuals that qualify for the stratification defined by the stratifying columns, aggregated over the reporting period.

Died

float

The number of deaths among individuals that qualify for the stratification defined by the stratifying columns, aggregated over the reporting period.

Died_from_HIV

float

The number of deaths due to HIV (as opposed to background mortality) among individuals that qualify for the stratification defined by the stratifying columns, aggregated over the reporting period.

Newly Tested Positive

float

The number of positive HIV tests that occurred during the reporting period.

Newly Tested Negative

float

The number of negative HIV tests that occurred during the reporting period.

Transmitters

float

If the Report_HIV_ByAgeAndGender_Add_Transmitters parameter is set to 1, then this column will be added to the report. It indicates the total number of the individuals qualifying for that row who transmitted HIV during this reporting period. This may not add up to the number of new infections in the reporting period if any of the new infections were due to the OutbreakIndividual intervention or maternal transmission.

<Event Name>

float

If the Report_HIV_ByAgeAndGender_Event_Counter_List parameter has event names specified, there will be one column for each individual event name. The values in the column will be the count of the events that occurred during the reporting period for individuals qualifying for that row. For example, if the rows were stratified by HasHIV and the person was uninfected when the event occurred they would be counted in the HasHIV=0 row. However, if at the end of the reporting period the person had become infected, they would counted in the HasHIV=1 row.
Example

The following is an example of a ReportHIVByAgeAndGender.csv report:

Year

NodeId

Gender

IP_Key:Adherence

HasIntervention:STIBarrier_NoCondoms

IsCircumcised

HIV_Stage

Age

Population

Infected CD4 Under 200 (Not On ART)

Infected CD4 200 To 349 (Not On ART)

Infected CD4 350 To 499 (Not On ART)

Infected CD4 500 Plus (Not On ART)

Infected

Newly Infected

On_ART

Died

Died_from_HIV

Tested Past Year or On_ART

Tested Ever

Diagnosed

Newly Tested Positive

Newly Tested Negative

Transmitters

HasIntervention(CoitalActRiskFactors_MoreLikelyToTransmit)

EnteredRelationship

ExitedRelationship

Currently (TRANSITORY)

Currently (INFORMAL)

Currently (MARITAL)

Currently (COMMERCIAL)

Ever (TRANSITORY)

Ever (INFORMAL)

Ever (MARITAL)

Ever (COMMERCIAL)

Has Concurrent Partners

Current Partners

Lifetime Partners

Num_TRANSITORY

Num_INFORMAL

Num_MARITAL

Num_COMMERCIAL

Num_Concordant_TRANSITORY

Num_Concordant_INFORMAL

Num_Concordant_MARITAL

Num_Concordant_COMMERCIAL

1963.37

1

0

LOW

0

0

NOT_INFECTED

15

911

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

27

35

337

450

18

0

607

574

19

0

322

1059

2424

432

609

18

0

392

568

18

0

1963.37

1

0

LOW

0

0

NOT_INFECTED

40

876

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

0

8

10

96

275

133

0

252

403

137

0

133

558

996

106

319

133

0

106

319

132

0

1963.37

1

0

LOW

0

0

ACUTE

15

3

0

0

0

3

3

2

0

0

0

0

0

0

0

0

1

0

0

0

1

2

0

0

3

2

0

0

2

6

10

3

3

0

0

2

2

0

0

1963.37

1

0

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

0

LATENT

15

46

13

10

19

4

46

0

0

0

0

0

0

0

0

0

0

0

3

2

23

39

3

0

42

44

3

0

31

84

179

30

51

3

0

6

23

1

0

1963.37

1

0

LOW

0

0

LATENT

40

1

0

0

0

1

1

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

0

0

1

1

0

0

1

3

3

1

2

0

0

0

1

0

0

1963.37

1

0

LOW

0

0

AIDS

15

3

3

0

0

0

3

0

0

1

1

0

0

0

0

0

1

0

1

1

2

2

0

0

3

3

0

0

2

6

14

3

3

0

0

2

1

0

0

1963.37

1

0

LOW

0

0

AIDS

40

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

0

4

3

20

30

3

0

30

33

3

0

23

66

143

25

38

3

0

9

17

2

0

1963.37

1

0

LOW

0

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

1

1

1

0

1

2

1

0

1

3

4

1

1

1

0

0

0

1

0

1963.37

1

0

LOW

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

0

NOT_INFECTED

15

671

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

34

31

308

415

14

0

580

546

15

0

320

1008

2346

416

578

14

0

390

530

14

0

1963.37

1

0

LOW

1

0

NOT_INFECTED

40

57

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

4

16

26

11

0

33

44

11

0

17

61

133

18

32

11

0

18

32

11

0

1963.37

1

0

LOW

1

0

ACUTE

15

3

0

0

0

3

3

2

0

0

0

0

0

0

0

0

1

0

0

0

3

2

0

0

3

3

0

0

3

8

14

5

3

0

0

4

1

0

0

1963.37

1

0

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

0

LATENT

15

20

4

5

10

1

20

0

0

0

0

0

0

0

0

0

0

0

2

0

10

13

0

0

19

18

0

0

12

31

84

15

16

0

0

10

8

0

0

1963.37

1

0

LOW

1

0

LATENT

40

5

4

0

1

0

5

0

0

0

0

0

0

0

0

0

0

0

1

1

2

3

0

0

3

4

0

0

2

6

10

2

4

0

0

0

0

0

0

1963.37

1

0

LOW

1

0

AIDS

15

2

1

0

0

0

2

0

1

1

1

1

0

0

0

0

0

0

0

2

2

1

0

0

2

2

0

0

1

3

9

2

1

0

0

1

0

0

0

1963.37

1

0

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

0

ON_ART

15

36

0

0

0

0

36

0

36

0

0

36

0

0

0

0

2

0

1

0

21

27

0

0

32

34

0

0

25

72

154

28

44

0

0

12

22

0

0

1963.37

1

0

LOW

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

0

1

0

0

2

1

0

0

0

1

5

0

1

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

LOW

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

0

NOT_INFECTED

15

945

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

33

33

338

491

18

0

633

604

18

0

354

1141

2463

447

676

18

0

405

619

16

0

1963.37

1

0

HIGH

0

0

NOT_INFECTED

40

875

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

0

11

10

84

274

135

0

229

397

138

0

121

542

967

86

321

135

0

86

316

134

0

1963.37

1

0

HIGH

0

0

ACUTE

15

4

0

0

1

3

4

0

0

0

0

0

0

0

0

0

1

0

0

0

2

4

1

0

4

4

1

0

4

10

22

2

7

1

0

0

5

0

0

1963.37

1

0

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

0

LATENT

15

42

15

5

18

4

42

0

0

0

0

0

0

0

0

0

1

0

2

1

23

30

4

0

39

40

4

0

28

75

172

33

38

4

0

15

18

0

0

1963.37

1

0

HIGH

0

0

LATENT

40

2

1

1

0

0

2

0

0

0

0

0

0

0

0

0

0

0

0

0

0

2

0

0

2

2

0

0

0

2

6

0

2

0

0

0

1

0

0

1963.37

1

0

HIGH

0

0

AIDS

15

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

1

1

0

0

0

1

2

0

1

0

0

0

1

0

0

1963.37

1

0

HIGH

0

0

AIDS

40

2

2

0

0

0

2

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

0

1

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

0

ON_ART

15

26

0

0

0

0

26

0

26

0

0

26

0

0

0

0

0

0

2

0

9

9

2

0

20

19

2

0

10

28

84

13

13

2

0

3

3

0

0

1963.37

1

0

HIGH

0

0

ON_ART

40

3

0

0

0

0

3

0

3

0

0

3

0

0

0

0

0

0

1

0

1

2

1

0

2

3

1

0

2

5

9

1

3

1

0

0

1

0

0

1963.37

1

0

HIGH

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

0

NOT_INFECTED

15

652

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

31

27

294

424

18

0

544

528

18

0

311

975

2208

371

586

18

0

342

557

17

0

1963.37

1

0

HIGH

1

0

NOT_INFECTED

40

46

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

2

1

13

22

3

0

29

34

3

0

9

44

96

15

26

3

0

14

26

3

0

1963.37

1

0

HIGH

1

0

ACUTE

15

9

0

0

0

9

9

2

0

0

0

0

0

0

0

0

1

0

0

0

7

6

0

0

8

9

0

0

6

19

39

10

9

0

0

8

6

0

0

1963.37

1

0

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

0

LATENT

15

31

13

3

8

7

31

0

0

0

0

0

0

0

0

0

0

0

3

1

16

26

0

0

27

30

0

0

18

58

118

23

35

0

0

8

16

0

0

1963.37

1

0

HIGH

1

0

LATENT

40

4

2

0

2

0

4

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

1

0

3

1

1

0

1

3

6

1

1

1

0

0

0

0

0

1963.37

1

0

HIGH

1

0

AIDS

15

4

4

0

0

0

4

0

0

0

0

0

0

0

0

0

0

0

0

0

2

3

0

0

4

4

0

0

3

7

15

2

5

0

0

1

1

0

0

1963.37

1

0

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

0

ON_ART

15

25

0

0

0

0

25

0

25

0

0

25

0

0

0

0

0

0

1

1

9

21

0

0

20

24

0

0

13

45

103

14

31

0

0

2

7

0

0

1963.37

1

0

HIGH

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

1

0

0

0

0

1

2

0

0

0

0

4

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

0

HIGH

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

0

0

NOT_INFECTED

15

1639

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

751

75

78

672

1034

77

0

1212

1267

81

0

773

2397

5318

901

1419

77

0

837

1314

72

0

1963.37

1

1

LOW

0

0

NOT_INFECTED

40

982

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

46

6

3

55

157

98

0

154

258

104

0

38

325

588

58

169

98

0

57

168

98

0

1963.37

1

1

LOW

0

0

ACUTE

15

12

0

0

0

12

12

5

0

0

0

0

0

0

0

0

1

7

0

1

10

9

1

0

10

11

1

0

10

27

58

12

14

1

0

9

6

0

0

1963.37

1

1

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

0

0

LATENT

15

61

1

9

36

15

61

0

0

0

0

0

0

0

0

0

2

38

3

5

38

48

0

0

61

57

1

0

38

122

304

51

71

0

0

16

35

0

0

1963.37

1

1

LOW

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

0

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

0

0

ON_ART

15

46

0

0

0

0

46

0

46

0

0

46

0

0

0

0

0

33

5

2

25

39

4

0

44

46

4

0

32

95

232

35

56

4

0

12

23

3

0

1963.37

1

1

LOW

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

0

0

0

0

1

0

0

0

1

0

0

0

1

1

0

1

0

0

0

1

0

0

1963.37

1

1

LOW

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

LOW

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

0

0

NOT_INFECTED

15

1582

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

703

63

55

658

989

87

0

1185

1219

90

0

732

2303

5145

858

1358

87

0

792

1288

81

0

1963.37

1

1

HIGH

0

0

NOT_INFECTED

40

969

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

60

5

12

58

170

95

0

179

278

99

0

51

343

638

60

188

95

0

60

187

94

0

1963.37

1

1

HIGH

0

0

ACUTE

15

11

0

0

0

11

11

3

0

0

0

0

0

0

0

0

3

6

0

1

9

10

0

0

10

11

0

0

9

28

54

15

13

0

0

9

7

0

0

1963.37

1

1

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

0

0

LATENT

15

82

2

5

53

22

82

0

0

0

0

0

0

0

0

0

0

49

8

4

53

70

3

0

77

81

3

0

60

178

416

71

104

3

0

24

49

1

0

1963.37

1

1

HIGH

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

0

0

AIDS

15

3

2

0

0

0

3

0

1

0

0

1

0

0

0

0

0

2

0

0

2

2

0

0

3

2

0

0

2

5

10

2

3

0

0

2

2

0

0

1963.37

1

1

HIGH

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

21

2

2

25

35

1

0

36

36

2

0

31

88

214

35

52

1

0

11

11

0

0

1963.37

1

1

HIGH

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

1

0

0

0

0

0

0

1

0

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.37

1

1

HIGH

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

0

NOT_INFECTED

15

917

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

42

25

346

453

18

0

616

578

19

0

329

1076

2466

443

615

18

0

402

573

18

0

1963.41

1

0

LOW

0

0

NOT_INFECTED

40

876

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

13

12

94

274

133

0

253

407

137

0

135

559

1009

104

322

133

0

104

322

132

0

1963.41

1

0

LOW

0

0

ACUTE

15

3

0

0

0

3

3

0

0

0

0

0

0

0

0

0

0

0

0

0

1

2

0

0

3

2

0

0

2

6

10

3

3

0

0

2

2

0

0

1963.41

1

0

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

0

LATENT

15

46

13

10

20

3

46

0

0

0

0

0

0

0

0

0

0

0

1

6

24

37

3

0

42

44

3

0

31

79

180

28

48

3

0

5

20

1

0

1963.41

1

0

LOW

0

0

LATENT

40

1

0

0

0

1

1

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

0

0

1

1

0

0

1

3

3

1

2

0

0

0

1

0

0

1963.41

1

0

LOW

0

0

AIDS

15

2

2

0

0

0

2

0

0

1

1

0

0

0

0

0

0

0

0

3

1

1

0

0

2

2

0

0

1

3

10

2

1

0

0

1

1

0

0

1963.41

1

0

LOW

0

0

AIDS

40

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

0

0

3

18

30

3

0

30

33

3

0

21

63

143

23

37

3

0

8

16

2

0

1963.41

1

0

LOW

0

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

1

1

1

0

1

2

1

0

1

3

4

1

1

1

0

0

0

1

0

1963.41

1

0

LOW

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

0

NOT_INFECTED

15

669

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

34

25

310

417

15

0

579

547

16

0

318

1016

2373

419

582

15

0

394

533

15

0

1963.41

1

0

LOW

1

0

NOT_INFECTED

40

58

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

2

1

16

26

11

0

34

45

11

0

17

62

138

20

31

11

0

20

31

11

0

1963.41

1

0

LOW

1

0

ACUTE

15

4

0

0

0

4

4

1

0

0

0

0

0

0

0

0

0

0

0

0

4

2

0

0

4

3

0

0

3

9

18

6

3

0

0

5

1

0

0

1963.41

1

0

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

0

LATENT

15

20

4

5

10

1

20

0

0

0

0

0

0

0

0

0

0

0

0

2

10

12

0

0

19

18

0

0

10

29

84

14

15

0

0

10

7

0

0

1963.41

1

0

LOW

1

0

LATENT

40

5

4

0

1

0

5

0

0

0

0

0

0

0

0

0

0

0

1

0

3

3

0

0

3

4

0

0

2

7

11

3

4

0

0

0

0

0

0

1963.41

1

0

LOW

1

0

AIDS

15

2

1

0

0

0

2

0

1

0

0

1

0

0

0

0

0

0

0

0

2

1

0

0

2

2

0

0

1

3

9

2

1

0

0

1

0

0

0

1963.41

1

0

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

0

ON_ART

15

36

0

0

0

0

36

0

36

0

0

36

0

0

0

0

0

0

5

2

23

26

0

0

32

34

0

0

26

75

159

31

44

0

0

14

22

0

0

1963.41

1

0

LOW

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

0

1

0

0

2

1

0

0

0

1

5

0

1

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

LOW

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

0

NOT_INFECTED

15

951

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

42

35

342

497

18

0

638

611

18

0

359

1151

2509

449

684

18

0

408

623

16

0

1963.41

1

0

HIGH

0

0

NOT_INFECTED

40

875

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

19

11

86

280

137

0

234

404

140

0

124

550

986

89

324

137

0

89

319

136

0

1963.41

1

0

HIGH

0

0

ACUTE

15

4

0

0

1

3

4

0

0

0

0

0

0

0

0

0

0

0

0

0

2

4

1

0

4

4

1

0

4

10

22

2

7

1

0

0

5

0

0

1963.41

1

0

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

0

LATENT

15

42

15

5

18

4

42

0

0

0

0

0

0

0

0

0

0

0

1

3

22

30

4

0

39

40

4

0

26

73

173

31

38

4

0

14

18

0

0

1963.41

1

0

HIGH

0

0

LATENT

40

2

1

1

0

0

2

0

0

0

0

0

0

0

0

0

0

0

0

0

0

2

0

0

2

2

0

0

0

2

6

0

2

0

0

0

1

0

0

1963.41

1

0

HIGH

0

0

AIDS

15

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

1

1

0

0

0

1

2

0

1

0

0

0

1

0

0

1963.41

1

0

HIGH

0

0

AIDS

40

2

2

0

0

0

2

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

0

1

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

0

ON_ART

15

26

0

0

0

0

26

0

26

0

0

26

0

0

0

0

0

0

0

2

9

9

2

0

20

19

2

0

8

26

84

13

11

2

0

3

3

0

0

1963.41

1

0

HIGH

0

0

ON_ART

40

3

0

0

0

0

3

0

3

0

0

3

0

0

0

0

0

0

0

0

1

2

1

0

2

3

1

0

2

5

9

1

3

1

0

0

1

0

0

1963.41

1

0

HIGH

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

0

NOT_INFECTED

15

650

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

39

25

291

431

18

0

544

533

18

0

308

984

2242

372

594

18

0

342

565

17

0

1963.41

1

0

HIGH

1

0

NOT_INFECTED

40

47

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

14

23

3

0

31

35

3

0

11

47

100

16

28

3

0

15

28

3

0

1963.41

1

0

HIGH

1

0

ACUTE

15

8

0

0

0

8

8

1

0

0

0

0

0

0

0

0

1

0

0

0

5

6

0

0

6

8

0

0

5

17

31

7

10

0

0

6

6

0

0

1963.41

1

0

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

0

LATENT

15

33

13

3

10

7

33

0

0

0

0

0

0

0

0

0

0

0

4

5

20

25

0

0

29

32

0

0

21

61

132

28

33

0

0

12

15

0

0

1963.41

1

0

HIGH

1

0

LATENT

40

4

2

0

2

0

4

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

1

0

3

1

1

0

1

3

6

1

1

1

0

0

0

0

0

1963.41

1

0

HIGH

1

0

AIDS

15

2

2

0

0

0

2

0

0

2

2

0

0

0

0

0

0

0

0

3

1

2

0

0

2

2

0

0

2

4

9

1

3

0

0

0

0

0

0

1963.41

1

0

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

0

ON_ART

15

25

0

0

0

0

25

0

25

0

0

25

0

0

0

0

0

0

0

2

9

20

0

0

20

24

0

0

13

43

103

13

30

0

0

2

7

0

0

1963.41

1

0

HIGH

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

1

0

0

1

0

0

1

2

0

0

0

1

5

0

1

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

0

HIGH

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

0

0

NOT_INFECTED

15

1639

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

749

76

58

680

1036

76

0

1216

1274

80

0

785

2414

5393

908

1430

76

0

845

1328

71

0

1963.41

1

1

LOW

0

0

NOT_INFECTED

40

985

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

48

13

7

57

159

99

0

157

264

105

0

40

334

605

62

173

99

0

60

172

99

0

1963.41

1

1

LOW

0

0

ACUTE

15

10

0

0

0

10

10

0

0

0

0

0

0

0

0

0

1

6

0

0

9

8

0

0

9

9

0

0

9

24

54

11

13

0

0

8

6

0

0

1963.41

1

1

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

0

0

LATENT

15

63

1

10

39

13

63

0

0

0

0

0

0

0

0

0

0

39

5

5

38

50

1

0

62

59

2

0

38

125

313

53

71

1

0

17

33

0

0

1963.41

1

1

LOW

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

0

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

0

0

ON_ART

15

46

0

0

0

0

46

0

46

0

0

46

0

0

0

0

0

33

3

1

26

38

4

0

44

46

4

0

32

97

235

36

57

4

0

13

23

3

0

1963.41

1

1

LOW

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

0

0

0

0

1

0

0

0

1

0

0

0

1

1

0

1

0

0

0

1

0

0

1963.41

1

1

LOW

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

LOW

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

0

0

NOT_INFECTED

15

1581

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

701

84

78

657

987

89

0

1188

1225

92

0

735

2306

5226

859

1358

89

0

796

1290

83

0

1963.41

1

1

HIGH

0

0

NOT_INFECTED

40

971

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

61

11

4

60

176

96

0

181

286

100

0

50

351

650

62

193

96

0

62

192

95

0

1963.41

1

1

HIGH

0

0

ACUTE

15

12

0

0

0

12

12

1

0

0

0

0

0

0

0

0

1

7

2

0

10

11

0

0

11

11

0

0

10

32

58

18

14

0

0

11

7

0

0

1963.41

1

1

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

0

0

LATENT

15

82

2

6

54

20

82

0

0

0

0

0

0

0

0

0

0

49

6

9

52

70

3

0

77

81

3

0

63

175

422

69

103

3

0

23

46

1

0

1963.41

1

1

HIGH

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

0

0

AIDS

15

2

1

0

0

0

2

0

1

1

1

1

0

0

0

0

0

2

0

2

1

2

0

0

2

2

0

0

1

3

9

1

2

0

0

1

1

0

0

1963.41

1

1

HIGH

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

21

1

3

24

34

1

0

36

36

2

0

29

86

215

33

52

1

0

10

10

0

0

1963.41

1

1

HIGH

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

1

0

0

0

0

0

0

1

0

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.41

1

1

HIGH

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

0

NOT_INFECTED

15

921

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

40

33

341

456

19

0

617

581

20

0

332

1078

2495

443

616

19

0

404

575

19

0

1963.45

1

0

LOW

0

0

NOT_INFECTED

40

874

0

0

0

0

0

0

0

2

0

0

0

0

0

0

0

0

14

15

94

271

134

0

257

408

138

0

132

558

1019

104

320

134

0

104

320

133

0

1963.45

1

0

LOW

0

0

ACUTE

15

5

0

0

0

5

5

2

0

0

0

0

0

0

0

0

2

0

1

0

3

4

0

0

5

4

0

0

4

12

22

6

6

0

0

4

4

0

0

1963.45

1

0

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

0

LATENT

15

45

13

9

20

3

45

0

0

0

0

0

0

0

0

0

0

0

4

1

23

38

3

0

42

43

3

0

31

81

182

28

50

3

0

4

20

1

0

1963.45

1

0

LOW

0

0

LATENT

40

2

0

1

0

1

2

0

0

0

0

0

0

0

0

0

0

0

0

0

2

1

0

0

2

2

0

0

1

4

5

2

2

0

0

0

1

0

0

1963.45

1

0

LOW

0

0

AIDS

15

2

2

0

0

0

2

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

0

0

2

2

0

0

1

3

10

2

1

0

0

1

1

0

0

1963.45

1

0

LOW

0

0

AIDS

40

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

0

1

1

18

30

3

0

31

33

3

0

21

63

144

23

37

3

0

8

16

2

0

1963.45

1

0

LOW

0

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

1

1

1

0

1

2

1

0

1

3

4

1

1

1

0

0

0

1

0

1963.45

1

0

LOW

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

0

NOT_INFECTED

15

666

0

0

0

0

0

0

0

2

0

0

0

0

0

0

0

0

26

38

310

418

15

0

580

548

16

0

312

1002

2386

410

577

15

0

384

527

15

0

1963.45

1

0

LOW

1

0

NOT_INFECTED

40

58

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

16

26

11

0

34

45

11

0

17

62

138

20

31

11

0

20

31

11

0

1963.45

1

0

LOW

1

0

ACUTE

15

5

0

0

0

5

5

1

0

0

0

0

0

0

0

0

0

0

0

0

5

3

0

0

5

4

0

0

4

11

22

7

4

0

0

6

1

0

0

1963.45

1

0

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

0

LATENT

15

19

4

5

10

0

19

0

0

1

0

0

0

0

0

0

0

0

2

5

10

10

0

0

18

17

0

0

8

26

81

12

14

0

0

9

7

0

0

1963.45

1

0

LOW

1

0

LATENT

40

5

4

0

1

0

5

0

0

0

0

0

0

0

0

0

0

0

0

0

3

3

0

0

3

4

0

0

2

7

11

3

4

0

0

0

0

0

0

1963.45

1

0

LOW

1

0

AIDS

15

2

1

0

0

0

2

0

1

0

0

1

0

0

0

0

0

0

0

0

2

1

0

0

2

2

0

0

1

3

9

2

1

0

0

1

0

0

0

1963.45

1

0

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

0

ON_ART

15

36

0

0

0

0

36

0

36

0

0

36

0

0

0

0

1

0

2

1

23

26

0

0

32

34

0

0

27

76

161

31

45

0

0

13

23

0

0

1963.45

1

0

LOW

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

0

1

0

0

2

1

0

0

0

1

5

0

1

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

LOW

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

0

NOT_INFECTED

15

950

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

0

44

28

345

495

17

0

641

611

17

0

365

1163

2543

456

690

17

0

411

626

15

0

1963.45

1

0

HIGH

0

0

NOT_INFECTED

40

876

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

10

11

84

282

141

0

235

410

144

0

122

550

998

87

322

141

0

87

316

140

0

1963.45

1

0

HIGH

0

0

ACUTE

15

4

0

0

0

4

4

1

0

0

0

0

0

0

0

0

0

0

0

3

2

3

1

0

4

4

1

0

3

8

23

3

4

1

0

1

2

0

0

1963.45

1

0

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

0

LATENT

15

43

15

6

18

4

43

0

0

0

0

0

0

0

0

0

0

0

4

0

23

32

4

0

40

41

4

0

27

79

180

34

41

4

0

14

19

0

0

1963.45

1

0

HIGH

0

0

LATENT

40

1

0

1

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

1

1

0

0

0

1

4

0

1

0

0

0

0

0

0

1963.45

1

0

HIGH

0

0

AIDS

15

1

1

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

0

1

1

0

0

0

1

2

0

1

0

0

0

1

0

0

1963.45

1

0

HIGH

0

0

AIDS

40

2

2

0

0

0

2

0

0

1

1

0

0

0

0

0

0

0

0

0

0

1

0

0

1

1

0

0

0

1

2

0

1

0

0

0

1

0

0

1963.45

1

0

HIGH

0

0

ON_ART

15

26

0

0

0

0

26

0

26

0

0

26

0

0

0

0

0

0

4

0

11

10

2

0

20

19

2

0

9

30

88

16

12

2

0

4

4

0

0

1963.45

1

0

HIGH

0

0

ON_ART

40

3

0

0

0

0

3

0

3

0

0

3

0

0

0

0

0

0

0

0

1

2

1

0

2

3

1

0

2

5

9

1

3

1

0

0

1

0

0

1963.45

1

0

HIGH

0

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

0

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

0

NOT_INFECTED

15

649

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

0

33

38

289

429

19

0

547

533

19

0

306

979

2270

368

592

19

0

336

558

17

0

1963.45

1

0

HIGH

1

0

NOT_INFECTED

40

47

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

14

23

3

0

31

35

3

0

11

47

100

16

28

3

0

15

28

3

0

1963.45

1

0

HIGH

1

0

ACUTE

15

6

0

0

0

6

6

0

0

0

0

0

0

0

0

0

1

0

1

1

3

5

0

0

4

6

0

0

3

13

22

5

8

0

0

4

5

0

0

1963.45

1

0

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

0

LATENT

15

35

13

4

10

8

35

0

0

0

0

0

0

0

0

0

0

0

4

3

22

26

0

0

31

34

0

0

21

66

146

32

34

0

0

15

16

0

0

1963.45

1

0

HIGH

1

0

LATENT

40

4

2

0

2

0

4

0

0

0

0

0

0

0

0

0

0

0

0

0

1

1

1

0

3

1

1

0

1

3

6

1

1

1

0

0

0

0

0

1963.45

1

0

HIGH

1

0

AIDS

15

2

2

0

0

0

2

0

0

0

0

0

0

0

0

0

2

0

0

0

1

2

0

0

2

2

0

0

2

4

9

1

3

0

0

0

2

0

0

1963.45

1

0

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

0

ON_ART

15

25

0

0

0

0

25

0

25

0

0

25

0

0

0

0

0

0

2

2

8

20

0

0

20

24

0

0

15

43

105

12

31

0

0

2

8

0

0

1963.45

1

0

HIGH

1

0

ON_ART

40

2

0

0

0

0

2

0

2

0

0

2

0

0

0

0

0

0

0

0

0

1

0

0

1

2

0

0

0

1

5

0

1

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

0

HIGH

1

1

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

0

0

NOT_INFECTED

15

1636

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

747

86

71

681

1037

77

0

1221

1278

81

0

785

2418

5461

912

1429

77

0

841

1327

72

0

1963.45

1

1

LOW

0

0

NOT_INFECTED

40

987

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

49

7

7

56

161

101

0

157

268

108

0

41

336

614

61

174

101

0

59

174

101

0

1963.45

1

1

LOW

0

0

ACUTE

15

10

0

0

0

10

10

3

0

0

0

0

0

0

0

0

1

5

1

2

10

7

0

0

10

8

0

0

9

24

56

13

11

0

0

8

4

0

0

1963.45

1

1

LOW

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

0

0

LATENT

15

66

1

11

40

14

66

0

0

0

0

0

0

0

0

0

1

41

4

3

40

52

1

0

64

62

2

0

43

134

332

56

77

1

0

19

38

0

0

1963.45

1

1

LOW

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

0

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

0

0

ON_ART

15

46

0

0

0

0

46

0

46

0

0

46

0

0

0

0

0

33

3

2

26

38

5

0

44

46

5

0

33

98

238

35

58

5

0

13

23

3

0

1963.45

1

1

LOW

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

0

0

0

0

1

0

0

0

1

0

0

0

1

1

0

1

0

0

0

1

0

0

1963.45

1

1

LOW

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

LOW

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

0

0

NOT_INFECTED

15

1578

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

698

70

76

654

982

90

0

1191

1225

94

0

733

2291

5278

852

1349

90

0

790

1278

84

0

1963.45

1

1

HIGH

0

0

NOT_INFECTED

40

973

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

63

4

11

56

175

97

0

183

290

101

0

49

346

660

58

191

97

0

58

190

96

0

1963.45

1

1

HIGH

0

0

ACUTE

15

13

0

0

0

13

13

3

0

0

0

0

0

0

0

0

2

6

2

0

10

13

0

0

12

13

0

0

11

38

65

20

18

0

0

14

7

0

0

1963.45

1

1

HIGH

0

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

0

0

LATENT

15

84

2

8

56

18

84

0

0

0

0

0

0

0

0

0

0

51

7

5

54

72

3

0

78

83

3

0

63

180

436

70

107

3

0

23

48

1

0

1963.45

1

1

HIGH

0

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

0

0

AIDS

15

2

1

0

0

0

2

0

1

1

1

1

0

0

0

0

0

2

0

2

0

1

0

0

2

2

0

0

0

1

9

0

1

0

0

0

0

0

0

1963.45

1

1

HIGH

0

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

0

0

ON_ART

15

37

0

0

0

0

37

0

37

0

0

37

0

0

0

0

0

21

6

2

24

34

1

0

36

36

2

0

30

90

221

35

54

1

0

9

11

0

0

1963.45

1

1

HIGH

0

0

ON_ART

40

1

0

0

0

0

1

0

1

0

0

1

0

0

0

0

0

1

0

0

0

0

0

0

1

0

0

0

0

0

2

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

NOT_INFECTED

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

NOT_INFECTED

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

ACUTE

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

ACUTE

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

LATENT

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

LATENT

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

AIDS

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

AIDS

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

ON_ART

15

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963.45

1

1

HIGH

1

0

ON_ART

40

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0
ReportHIVART

The ART initiation and discontinuation report (ReportHIVART.csv) provides information on individuals at time of ART initiation and discontinuation, including ID, age, gender, and CD4 count at ART initiation.

Configuration

To generate the report, set the configuration parameter Report_HIV_ART to 1.

Output file data

The output report will contain the following information.

Data channel

Data type

Description

Year

float

The time of the event (ART initiation or discontinuation) in units of calendar year, including fractions of years up to two decimal places.

Node_ID

integer

The identification number of the node.

ID

integer

The individual’s unique identifying number.

Gender

boolean

Identifies the individual’s gender: 0 is assigned to males, 1 is assigned to females.

Age

integer

The age of the individual in units of days. Divide by 365 to obtain age in years.

CD4

float

The last CD4 count taken when the person started or stopped ART, as measured with the HIVDrawBlood intervention. -1 indicates that the person has not had their CD4 count measured using HIVDrawBlood.

StartingART

boolean

Identifies the ART initiation or discontinuation event: 1 indicates the individual has initiated ART, 0 indicates they are discontinuing ART.
Example

The following is an example of a ReportHIVART.csv report:

Year

Node_ID

ID

Age

Gender

CD4

StartingART

2004.08

1

27706

11284.6

0

161.839

1

2004.08

1

10201

19987.1

1

110.123

1

2004.08

1

15913

16207.9

0

45.5525

1

2004.08

1

23409

13109.6

0

72.0657

1

2004.17

1

23622

13048.8

1

55.3341

1

2004.17

1

20534

14448

1

67.7487

1

2004.17

1

31178

9946.25

1

98.1908

1

2004.17

1

33985

8942.49

1

118.728

1

2004.25

1

1115

18274

0

367.871

1

2004.25

1

4269

17502.4

1

180.849

1

2004.25

1

18372

15512.6

0

92.4468

1

2004.25

1

22219

13718

1

137.515

1

2004.25

1

35535

8425.4

1

67.4645

1

2004.33

1

21923

13900.5

1

57.9216

1

2004.33

1

2263

17260.2

1

68.6523

1

2004.33

1

29534

10645.8

0

51.6956

1

2004.33

1

30617

10220

0

175.078

1

2004.33

1

31062

10067.9

1

55.5745

1

2004.33

1

32240

9611.66

1

60.6885

1

2004.42

1

423

17755.7

1

47.3852

1

2004.42

1

2176

20670.7

0

72.4489

1

2004.42

1

32197

9672.5

1

77.1323

1

2004.42

1

33190

9307.49

1

150.854

1

2004.42

1

8695

23253.8

1

58.3088

1

2004.42

1

19267

15147.6

1

99.4895

1

2004.42

1

21794

13961.3

1

43.2681

1

2004.42

1

23259

13292.1

0

42.9684

1

2004.42

1

25132

12470.9

0

60.7807

1

2004.5

1

28245

11223.8

1

75.9129

1

2004.5

1

2680

16309.4

0

42.8907

1

2004.5

1

10963

19110.7

1

45.7188

1

2004.5

1

17339

19473.5

0

156.149

1

2004.5

1

17731

15908

1

34.7817

1

2004.5

1

21051

14356.7

0

61.632

1
ReportHIVInfection

The HIV disease progression report (ReportHIVInfection.csv) provides information on each individual’s disease state at each time step, including age, gender, CD4 count, survival prognosis, ART status, and factors impacting transmission and acquisition.

Configuration

To generate the report, the following parameters must be configured in the config.json file:

Parameter

Data type

Min

Max

Default

Description

Report_HIV_Infection

boolean

NA

NA

0

Set this to 1 to generate the report.

Report_HIV_Infection_Start_Year

float

1900

2200

1900

Simulation time in years to start collecting data.

Report_HIV_Infection_Stop_Year

float

1900

2200

2200

Simulation time in years to start collecting data.

 
{
    "Report_HIV_Infection": 1,
    "Report_HIV_Infection_Start_Year": 1940,
    "Report_HIV_Infection_Stop_Year": 2000
}
Output file data

The output report will contain the following information.

Data columns

Data channel

Data type

Description

Year

float

Simulation time in years, including fractions of years.

Node_ID

integer

The identification number of the node.

Id

integer

The unique identification number of the individual.

MCWeight

integer

Not currently supported. This column will always show a Monte Carlo weight of 1.

Age

float

The age of the individual in years, including fractions of years.

Gender

boolean

Identifies the individual’s gender: 0 is assigned to males, 1 is assigned to females.

getProbMaternalTransmission

float

The hypothetical probability of mother-to-child transmission (MTCT), if the individual were to give birth at the present time and not receive any interventions such as PMTCT or AntiretroviralTherapy. Not applicable for males or for females of non-childbearing age.

TimeSinceHIV

float

The number of days since the individual became infected. Note: If the individual was infected by an OutbreakIndividual intervention with the Incubation_Period_Override parameter set to 0, the infected date will be randomly set in the past (uniformly selected from the amount of time until death). TimeSinceHIV will count accordingly from the ‘historic’ infection date.

CD4count

float

The current CD4 count, regardless of when CD4 testing was performed.

PrognosisCompletedFraction

float

The proportion of the total untreated HIV survival time that has already been lived; only relevant when the individual is not on ART.

Prognosis

float

The remaining untreated survival time until AIDS-related death; only relevant when the individual is not on ART.

Stage

integer

The individual’s disease stage. Possible values are:

  • 0 = Uninfected

  • 1 = Untreated acute HIV infection

  • 2 = Untreated latent HIV infection

  • 3 = Untreated late/AIDS stage

  • 4 = On ART

ViralLoad

float

Not currently supported.

WHOStage

float

The individual’s WHO stage, linearly interpolated between integer values. Round down to obtain the integer value for the WHO clinical stage. Uninfected individuals will be assigned a value of -1.

Infectiousness

float

Describes the individual’s infectiousness, which depends on the disease stage and ART status, and includes effects of heterogeneous infectiousness.

ModAcquire

float

Multiplicative modifier on disease acquisition; will be set to 1 by default for HIV, but can be impacted by the IndividualImmunityChanger intervention or by setting Enable_Maternal_Protection to 1 in the config.json file.

ModTransmit

float

Multiplicative modifier on disease transmission; will be set to 1 by default for HIV, but can be impacted by the IndividualImmunityChanger intervention.

ModMortality

float

Multiplicative modifier on disease mortality; will be set to 1 by default for HIV, but can be impacted by the IndividualImmunityChanger intervention.

ArtStatus

integer

Describes the individual’s ART status. Possible values are:

  • 1 = The individual is not currently receiving ART.

  • 5 = The individual is on ART, but their viral load is not yet suppressed.

  • 6 = The individual is on ART, and their viral load is suppressed.

  • 7 = The individual is on ART, but is experiencing virological failure.

  • 8 = The individual has had poor adherence to ART.

  • 9 = The individual has dropped out of ART.

InfectivitySuppression

float

The multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV-positive individual. This can be reduced from ART_Viral_Suppression_Multiplier due to ARTBasic’s Days_To_Achieve_Viral_Suppression.

DurationOnArt

integer

The number of days since the individual most recently started ART. Set to -1 if they are not on ART.

ProbMaternalTransmissionModifier

float

The better maternal transmission multiplier provided by PMTCT, or zero.

OnArtQuery

boolean

Describes whether the individual is on ART or not: 0 if individual is not on ART, and 1 if they are.

CoInfectiveTransmissionFactor

float

If the person has an STI co-infection (set by the ModifyStiCoInfectionStatus intervention), then this will be the value from the parameter STI_Coinfection_Transmission_Multiplier. Otherwise, the value will be 1.

CoInfectiveAcquisitionFactor

float

If the person has an STI co-infection (set by the ModifyStiCoInfectionStatus intervention), then this will be the value from the parameter STI_Coinfection_Acquisition_Multiplier. Otherwise, the value will be 1.

DebutAge

float

The age of sexual debut in days.

IsCircumcised

boolean

Indicates whether or not the individual is circumcised (only applicable to males): 0 for not circumcised (and females), 1 for circumcised.

InterventionReducedAcquire

float

The multiplier, based on interventions like SimpleVaccine, used to reduce the probability that an individual will acquire an infection.

InterventionReducedTransmit

float

The multiplier, based on interventions like SimpleVaccine, used to reduce the probability that an individual will transmit an infection.

InterventionReducedMortality

float

The multiplier, based on interventions like SimpleVaccine, used to reduce the probability that an individual will die due to an infection.
Example

The following is an example of a ReportHIVInfection.csv file.

Year

Node_ID

Id

MCWeight

Age

Gender

getProbMaternalTransmission

TimeSinceHIV

CD4count

PrognosisCompletedFraction

Prognosis

Stage

ViralLoad

WHOStage

Infectiousness

ModAcquire

ModTransmit

ModMortality

ArtStatus

InfectivitySuppression

DurationOnART

ProbMaternalTransmissionModifier

OnArtQuery

CoInfectiveTransmissionFactor

CoInfectiveAcquisitionFactor

DebutAge

IsCircumcised

InterventionReducedAcquire

InterventionReducedTransmit

InterventionReducedMortality

1960.502686

1

2

1

0.307482409

1

0.300000012

0

538.1308594

0.002955006

338.4078064

1

10000

1.012042642

0.026000001

1

1

1

1

1

-1

0

0

1

1

5090.935059

0

1

1

1

1960.502686

1

3

1

21.57338533

1

0.300000012

0

540.4145508

0.000165243

6050.577637

1

10000

1.00041461

0.026000001

1

1

1

1

1

-1

0

0

10

10

5013.489746

0

1

1

1

1960.502686

1

4

1

1.316084269

0

0.300000012

0

540.4000244

0.00018299

5463.524414

1

10000

1.000959992

0.026000001

1

1

1

1

1

-1

0

0

1

1

5758.322754

0

1

1

1

1960.502686

1

5

1

4.214282895

1

0.300000012

0

540.4743652

9.23E-05

10828.31738

1

10000

1.000107288

0.026000001

1

1

1

1

1

-1

0

0

1

1

5784.283203

0

1

1

1

1960.502686

1

6

1

35.359375

1

0.300000012

0

540.2758179

0.000334598

2988.656494

1

10000

1.004073143

0.026000001

1

1

1

1

1

-1

0

0

1

1

5227.504883

0

1

1

1

1960.502686

1

7

1

64.59115475

0

0.300000012

0

539.5106812

0.001268703

788.182312

1

10000

1.003529072

0.026000001

1

1

1

1

1

-1

0

0

1

1

5978.607422

0

1

1

1

1960.502686

1

8

1

44.97678189

0

0.300000012

0

540.0627441

0.000594637

1681.643921

1

10000

1.002447605

0.026000001

1

1

1

1

1

-1

0

0

1

1

6403.728516

0

1

1

1

1960.502686

1

9

1

8.954728302

1

0.300000012

0

538.0894775

0.003005542

332.7134705

1

10000

1.003447533

0.026000001

1

1

1

1

1

-1

0

0

1

1

5457.208496

0

1

1

1

1960.502686

1

10

1

61.55059396

1

0.300000012

0

540.2617798

0.000351696

2843.225098

1

10000

1.003378153

0.026000001

1

1

1

1

1

-1

0

0

1

1

5853.435547

0

1

1

1

1960.505493

1

2

1

0.310222135

1

0.300000012

1

535.7171021

0.005910011

338.4078064

1

10000

1.024085283

0.026000001

1

1

1

1

1

-1

0

0

1

1

5090.935059

0

1

1

1

1960.505493

1

3

1

21.57612505

1

0.300000012

1

540.2791748

0.000330486

6050.577637

1

10000

1.00082922

0.026000001

1

1

1

1

1

-1

0

0

10

10

5013.489746

0

1

1

1

1960.505493

1

4

1

1.318823995

0

0.300000012

1

540.250061

0.00036598

5463.524414

1

10000

1.001919866

0.026000001

1

1

1

1

1

-1

0

0

1

1

5758.322754

0

1

1

1

1960.505493

1

5

1

4.217022621

1

0.300000012

1

540.3986816

0.000184613

10828.31738

1

10000

1.000214458

0.026000001

1

1

1

1

1

-1

0

0

1

1

5784.283203

0

1

1

1

1960.505493

1

6

1

35.36211473

1

0.300000012

1

540.0016479

0.000669197

2988.656494

1

10000

1.008146405

0.026000001

1

1

1

1

1

-1

0

0

1

1

5227.504883

0

1

1

1

1960.505493

1

7

1

64.59389448

0

0.300000012

1

538.4723511

0.002537407

788.182312

1

10000

1.007058144

0.026000001

1

1

1

1

1

-1

0

0

1

1

5978.607422

0

1

1

1

1960.505493

1

8

1

44.97952162

0

0.300000012

1

539.5757446

0.001189274

1681.643921

1

10000

1.004895329

0.026000001

1

1

1

1

1

-1

0

0

1

1

6403.728516

0

1

1

1

1960.505493

1

9

1

8.957468028

1

0.300000012

1

535.6346436

0.006011083

332.7134705

1

10000

1.006895065

0.026000001

1

1

1

1

1

-1

0

0

1

1

5457.208496

0

1

1

1

1960.505493

1

10

1

61.55333369

1

0.300000012

1

539.9736328

0.000703392

2843.225098

1

10000

1.006756186

0.026000001

1

1

1

1

1

-1

0

0

1

1

5853.435547

0

1

1

1

1960.508179

1

2

1

0.312961861

1

0.300000012

2

533.3087769

0.008865017

338.4078064

1

10000

1.036127925

0.026000001

1

1

1

1

1

-1

0

0

1

1

5090.935059

0

1

1

1

1960.508179

1

3

1

21.57886478

1

0.300000012

2

540.1437988

0.000495729

6050.577637

1

10000

1.001243949

0.026000001

1

1

1

1

1

-1

0

0

10

10

5013.489746

0

1

1

1

1960.508179

1

4

1

1.321563721

0

0.300000012

2

540.1001587

0.000548971

5463.524414

1

10000

1.002879858

0.026000001

1

1

1

1

1

-1

0

0

1

1

5758.322754

0

1

1

1

1960.508179

1

5

1

4.219762347

1

0.300000012

2

540.3230591

0.00027692

10828.31738

1

10000

1.000321746

0.026000001

1

1

1

1

1

-1

0

0

1

1

5784.283203

0

1

1

1

1960.508179

1

6

1

35.36485445

1

0.300000012

2

539.7276001

0.001003795

2988.656494

1

10000

1.012219548

0.026000001

1

1

1

1

1

-1

0

0

1

1

5227.504883

0

1

1

1

1960.508179

1

7

1

64.5966342

0

0.300000012

2

537.4350586

0.00380611

788.182312

1

10000

1.010587215

0.026000001

1

1

1

1

1

-1

0

0

1

1

5978.607422

0

1

1

1

1960.508179

1

8

1

44.98226134

0

0.300000012

2

539.0889282

0.001783911

1681.643921

1

10000

1.007342935

0.026000001

1

1

1

1

1

-1

0

0

1

1

6403.728516

0

1

1

1

1960.508179

1

9

1

8.960207754

1

0.300000012

2

533.1853638

0.009016625

332.7134705

1

10000

1.010342598

0.026000001

1

1

1

1

1

-1

0

0

1

1

5457.208496

0

1

1

1

1960.508179

1

10

1

61.55607342

1

0.300000012

2

539.6856079

0.001055089

2843.225098

1

10000

1.010134339

0.026000001

1

1

1

1

1

-1

0

0

1

1

5853.435547

0

1

1

1
HIVMortality

The HIV mortality report (HIVMortality.csv) provides information about individuals at the time of their death, including disease status, CD4 count, medical history, and relationship history.

Configuration

To generate the report, set the Report_HIV_Mortality parameter to 1 in the config.json file.

Output file data

The output report will contain the following information.

Data channel

Data type

Description

Node_ID

integer

The identification number of the node.

id

integer

The unique identification number of the individual.

Death_time

float

Simulation time, in days, when the individual died.

Death_was_HIV_cause

boolean

Indicates whether or not the death was due to HIV infection: 0 if death was due to background mortality, and 1 if death was due to HIV.

Gender

boolean

Identifies the individual’s gender: 0 is assigned to males, 1 is assigned to females.

Age

float

The age of the individual, in years, including fractions of years up to four decimal places.

Num_rels_just_prior_to_death

integer

The number of relationships in which the individual was participating just prior to death.

Num_rels_lifetime

integer

The total number of lifetime relationships for the individual.

HIV_disease_state_just_prior_to_death

integer

Describes the disease state prior to the individual’s death. Possible values are:

  • 0 = Uninfected

  • 1 = Untreated acute HIV infection

  • 2 = Untreated latent HIV infection

  • 3 = Untreated late/AIDS stage

  • 4 = On ART

Years_since_infection

float

The number of years since the individual was most recently infected. This can be reset if the infection is suppressed by the AntiretroviralTherapy or ARTMortalityTable interventions.

CD4_count_first_recorded

float

The first CD4 count ever recorded with CD4 testing (via the HIVDrawBlood intervention). The value will be -1 if the person never received an HIVDrawBlood intervention.

CD4_count_last_recorded

float

The most recent CD4 count recorded with CD4 testing (via the HIVDrawBlood intervention). The value will be -1 if the person never received an HIVDrawBlood intervention.

CD4_count_current

float

The actual CD4 count at the time of death (regardless of when CD4 testing was performed).

Days_since_CD4_blood_draw

integer

The time lag between the last CD4 test (via the HIVBloodDraw intervention) and the time of death.

Total_number_of_times_initiating_ART

integer

The number of lifetime ART initiations. ART initiation and adherence are determined by the AntiretroviralTherapy and ARTMortalityTable interventions.

Total_years_on_ART

float

The cumulative number of years on ART, including fractions of years.

Years_since_first_ART_initiation

float

The number of years since first ART initiation, including fractions of years.

Years_since_most_recent_ART_initiation

float

The number of years since the most recent ART initiation, including fractions of years.

ART_status_just_prior_to_death

enum

Describes the individual’s ART eligibility status at the time of death. Possible values are:

  • WITHOUT_ART_UNQALIFIED

  • WITHOUT_ART_QUALIFIED_BY_BASELINE

  • ON_PRE_ART

  • LOST_TO_FOLLOW_UP

  • ON_ART_BUT_NOT_VL_SUPPRESSED

  • ON_VL_SUPPRESSED

  • ON_BUT_FAILING

  • ON_BUT_ADHERENCE_POOR

  • OFF_BY_DROPOUT

Intervention_Status

string

The value of the InterventionStatus individual property (IP) for the person that died, at the time of death. If InterventionStatus has not been configured, then the value will be “None.” See Individual and node properties for information on configuring interventions.

Ever_tested

boolean

Describes whether or not the individual has ever received a diagnostic via the HIVRapidHIVDiagnostic intervention: 0 if the individual has not, and 1 if they have. Note that other diagnostics (such as SimpleDiagnostic and HIVSimpleDiagnostic) do not count toward Ever_tested.

Ever_tested_positive

boolean

Describes whether or not the individual has ever received a positive HIV test via the HIVRapidHIVDiagnostic intervention: 0 if the individual has not, and 1 if they have. Note that other diagnostics (such as SimpleDiagnostic and HIVSimpleDiagnostic) do not count toward Ever_tested_positive.

Ever_received_CD4_result

boolean

Describes whether or not individuals have received a CD4 test via the HIVDrawBlood intervention: 0 if the individual has not, and 1 if they have.

Ever_in_ART

boolean

Describes whether the individual has ever received ART via the AntiretroviralTherapy or ARTMortalityTable interventions: 0 if the individual has not, and 1 if they have.

Currently_in_ART

boolean

Describes whether or not the individual was receiving ART via the AntiretroviralTherapy or ARTMortalityTable interventions at the time of their death: 0 if the individual was not, and 1 if they were. Individual adherence to ART may be modified by the ARTMortalityTable intervention.
Example

The following is an example of a HIVMortality.csv report:

Node_ID

id

Death_time

Death_was_HIV_cause

Gender

Age

Num_rels_just_prior_to_death

Num_rels_lifetime

HIV_disease_state_just_prior_to_death

Years_since_infection

CD4_count_first_recorded

CD4_count_last_recorded

CD4_count_current

Days_since_CD4_blood_draw

Total_number_of_times_initiating_ART

Total_years_on_ART

Years_since_first_ART_initiation

Years_since_most_recent_ART_initiation

ART_status_just_prior_to_death

Intervention_Status

Ever_tested

Ever_tested_positive

Ever_received_CD4_result

Ever_in_ART

Currently_in_ART

1

29

7770

1

0

21.3699

0

0

3

1.31507

0

0

3.44695

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

38

8160

1

1

22.4384

0

0

3

2.38356

0

0

4.69059

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

92

8670

1

1

23.8356

0

0

3

3.78082

0

0

2.68563

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

37

8700

1

1

23.9178

0

0

3

3.86301

0

0

5.04478

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

98

8760

1

1

24.0822

0

0

3

4.0274

0

0

1.90831

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

64

9180

1

0

25.2329

0

0

3

5.17808

0

0

45.8134

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

25

9420

1

0

25.8904

0

0

3

5.83562

0

0

1.71753

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

11

9570

1

0

26.3014

0

0

3

6.24658

0

0

2.23987

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

10

9660

1

0

26.5479

0

0

3

6.49315

0

0

4.29309

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

78

9810

1

1

26.9589

0

0

3

6.90411

0

0

16.3808

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

41

9840

1

1

27.0411

0

0

3

6.9863

0

0

2.73176

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

34

9930

1

0

27.2877

0

0

3

7.23288

0

0

3.91411

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

52

9930

1

0

27.2877

0

0

3

7.23288

0

0

2.86028

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

71

10020

1

0

27.5342

0

0

3

7.47945

0

0

4.99421

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

3

10200

1

0

28.0274

0

0

3

7.9726

0

0

6.46508

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

72

10380

1

1

28.5205

0

0

3

8.46575

0

0

4.17088

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

42

10740

1

0

29.5068

0

0

3

9.45205

0

0

2.80336

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

67

10860

1

1

29.8356

0

0

3

9.78082

0

0

0.911652

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

85

11100

1

0

30.4932

0

0

3

10.4384

0

0

4.34908

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

76

11130

1

0

30.5753

0

0

3

10.5205

0

0

2.28753

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

59

11160

1

0

30.6575

0

0

3

10.6027

0

0

8.82356

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

62

11250

1

1

30.9041

0

0

3

10.8493

0

0

4.49486

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

23

11490

1

0

31.5616

0

0

3

11.5068

0

0

1.13325

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

75

11490

1

1

31.5616

0

0

3

11.5068

0

0

0.715854

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

50

11640

1

0

31.9726

0

0

3

11.9178

0

0

23.7552

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

2

11670

1

0

32.0548

0

0

3

2.05479

0

0

2.50851

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

53

11670

1

0

32.0548

0

0

3

12

0

0

1.06599

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

27

11910

1

0

32.7123

0

0

3

12.6575

0

0

10.0057

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

12

11970

1

0

32.8767

0

0

3

12.8219

0

0

6.57342

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

20

12000

1

1

32.9589

0

0

3

12.9041

0

0

28.8418

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

14

12210

1

0

33.5342

0

0

3

13.4795

0

0

3.77876

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

57

12390

1

0

34.0274

0

0

3

13.9726

0

0

18.1332

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

19

12510

1

1

34.3562

0

0

3

4.35616

0

0

4.2497

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

28

12630

1

0

34.6849

0

1

3

14.6301

0

0

3.95616

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0

1

54

12690

1

0

34.8493

0

0

3

4.84932

0

0

4.56509

0

0

0

0

0

WITHOUT_ART_UNQUALIFIED

None

0

0

0

0

0
RelationshipEnd

The relationship dissolution report (RelationshipEnd.csv) provides detailed information about each relationship and its members, evaluated at the time of relationship dissolution. The report includes the relationship type, start time, scheduled end time, actual end time (which may differ from the scheduled end time, for instance, due to the death of a partner), and information about each participant.

Configuration

To generate the report, set the Report_Relationship_End parameter to 1 in config.json file.

Output file data

The output report will contain the following information.

Data channel

Data type

Description

Rel_ID

integer

A unique identifier for the relationship, different from the IDs of the participants.

Node_ID

integer

The identification number for the node.

Rel_start_time

float

The time (in days) during the simulation when the relationship started.

Rel_scheduled_end_time

float

The time (in days) during the simulation when the relationship was scheduled to end. The duration of the relationship is dependent on the relationship type; configure by updating the Duration_Weibull_Heterogeneity and Duration_Weibull_Scale parameters in the demographics file. See Demographics parameters for details.

Rel_actual_end_time

float

The actual end time of the relationship, in days since the start of the simulation. This may differ from the scheduled end time due to the death of a partner, migration, etc.

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

integer

The type of relationship formed between the participants. Values for 0-3 as indicated in the header.

Is_rel_outside_PFA

boolean

Indicates whether or not the relationship was created by the normal process using the Pair Forming Algorithm (PFA), where “F” indicates the relationship was created using the PFA, and “T” indicates the relationship was created using the StartNewRelationship intervention.

male_ID

integer

A unique identifying number for the male partner in the relationship.

female_ID

integer

A unique identifying number for the female partner in the relationship.

male_age

float

The age, in years, of the male partner in the relationship.

female_age

float

The age, in years, of the female partner in the relationship.

num_total_coital_acts

integer

The total number of coital acts by the couple during this relationship.

Termination_Reason

enum

The reason the relationship was terminated. Possible values are:

  • NA

  • BROKEUP

  • SELF_MIGRATING

  • PARTNER_DIED

  • PARTNER_TERMINATED

  • PARTNER_MIGRATING
Example

The following is an example of a RelationshipEnd.csv report:

Rel_ID

Node_ID

Rel_start_time

Rel_scheduled_end_time

Rel_actual_end_time

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

Is_rel_outside_PFA

male_ID

female_ID

male_age

female_age

num_total_coital_acts

Termination_Reason

172161

10

3755.31

3757.6

3762.33

3

F

215107

47236

16.6732

46.0892

1

BROKEUP

172162

10

3755.31

3758.47

3762.33

3

F

215107

95405

16.6732

58.167

2

BROKEUP

172164

10

3755.31

3755.53

3762.33

3

F

208375

193954

28.9388

36.4973

1

BROKEUP

172165

10

3755.31

3756.35

3762.33

3

F

208375

95405

28.9388

58.167

2

BROKEUP

172166

10

3755.31

3756.44

3762.33

3

F

208375

717

28.9388

17.0808

1

BROKEUP

172169

10

3755.31

3758.32

3762.33

3

F

139812

717

42.8393

17.0808

3

BROKEUP

172171

10

3755.31

3756.94

3762.33

3

F

128988

717

16.526

17.0808

1

BROKEUP

172172

10

3755.31

3755.49

3762.33

3

F

128988

137623

16.526

39.5202

1

BROKEUP

172176

10

3755.31

3757.89

3762.33

3

F

111080

717

34.4271

17.0808

2

BROKEUP

172177

10

3755.31

3760.48

3762.33

3

F

111080

193954

34.4271

36.4973

1

BROKEUP

172180

10

3755.31

3762.1

3762.33

3

F

65716

47236

37.7356

46.0892

1

BROKEUP

172181

10

3755.31

3760.29

3762.33

3

F

65716

11486

37.7356

44.2118

3

BROKEUP

172185

10

3755.31

3756.74

3762.33

3

F

38645

113676

21.21

29.6195

2

BROKEUP

172186

10

3755.31

3758.99

3762.33

3

F

38645

193954

21.21

36.4973

1

BROKEUP

172187

10

3755.31

3758.87

3762.33

3

F

38645

11486

21.21

44.2118

4

BROKEUP

172188

10

3755.31

3755.8

3762.33

3

F

3016

717

43.5092

17.0808

1

BROKEUP

172163

10

3755.31

3762.66

3762.33

3

F

215107

137623

16.6924

39.5202

1

SELF_MIGRATING

172873

10

3762.33

3763.16

3762.33

3

F

215107

193954

16.6924

36.4973

2

SELF_MIGRATING

172872

10

3762.33

3765.23

3762.33

3

F

215107

717

16.6924

17.0808

2

SELF_MIGRATING

172871

10

3762.33

3764.99

3762.33

3

F

215107

47236

16.6924

46.0892

1

SELF_MIGRATING

172870

10

3762.33

3763.08

3762.33

3

F

215107

11486

16.6924

44.2118

1

SELF_MIGRATING

172862

10

3762.33

3769.33

3762.33

3

F

215107

113676

16.6924

29.6195

1

SELF_MIGRATING

172861

10

3762.33

3763.36

3762.33

3

F

215107

12476

16.6924

54.5147

2

SELF_MIGRATING

172168

10

3755.31

3771.16

3762.33

3

F

208375

11486

28.9581

44.2118

1

SELF_MIGRATING

172874

10

3762.33

3772.57

3762.33

3

F

208375

95405

28.9581

58.167

2

SELF_MIGRATING

172864

10

3762.33

3773.19

3762.33

3

F

208375

47236

28.9581

46.0892

1

SELF_MIGRATING

172863

10

3762.33

3765.92

3762.33

3

F

208375

12476

28.9581

54.5147

2

SELF_MIGRATING

172167

10

3755.31

3766.3

3762.33

3

F

208375

137623

28.9581

39.5202

5

SELF_MIGRATING

172182

10

3755.31

3776.06

3762.33

3

F

65716

193954

37.7356

36.5166

6

SELF_MIGRATING

172876

10

3762.33

3768.93

3762.33

3

F

139812

193954

42.8393

36.5166

1

SELF_MIGRATING

172892

10

3762.33

3771.79

3762.33

3

F

38645

193954

21.21

36.5166

3

SELF_MIGRATING

172867

10

3762.33

3775.52

3762.33

3

F

111080

193954

34.4271

36.5166

2

SELF_MIGRATING

172174

10

3755.31

3762.79

3762.33

3

F

128988

193954

16.526

36.5166

3

SELF_MIGRATING

172894

10

3762.33

3765

3762.33

3

F

3016

12476

43.5092

54.5339

2

PARTNER_DIED

172883

10

3762.33

3798.2

3762.33

3

F

111080

12476

34.4271

54.5339

2

PARTNER_DIED

172879

10

3762.33

3763.1

3762.33

3

F

139812

12476

42.8393

54.5339

1

PARTNER_DIED

172869

10

3762.33

3764.2

3762.33

3

F

38645

12476

21.21

54.5339

2

PARTNER_DIED

172866

10

3762.33

3767.01

3762.33

3

F

128988

12476

16.526

54.5339

2

PARTNER_DIED

172886

10

3762.33

3763.69

3762.33

3

F

65716

12476

37.7356

54.5339

1

PARTNER_DIED

172875

10

3762.33

3768.44

3762.33

3

F

139812

717

42.8585

17.0808

2

SELF_MIGRATING

172877

10

3762.33

3773.05

3762.33

3

F

139812

113676

42.8585

29.6195

2

SELF_MIGRATING

172878

10

3762.33

3781.56

3762.33

3

F

139812

137623

42.8585

39.5202

3

SELF_MIGRATING

172889

10

3762.33

3767.43

3762.33

3

F

38645

137623

21.21

39.5394

1

SELF_MIGRATING

172882

10

3762.33

3767.32

3762.33

3

F

111080

137623

34.4271

39.5394

3

SELF_MIGRATING

172170

10

3755.31

3765.79

3762.33

3

F

128988

95405

16.5453

58.167

4

SELF_MIGRATING

172865

10

3762.33

3763.14

3762.33

3

F

128988

11486

16.5453

44.2118

1

SELF_MIGRATING

172173

10

3755.31

3796.7

3762.33

3

F

128988

120936

16.5453

47.1905

1

SELF_MIGRATING

172880

10

3762.33

3771.85

3762.33

3

F

128988

717

16.5453

17.0808

1

SELF_MIGRATING

172175

10

3755.31

3764.35

3762.33

3

F

128988

47236

16.5453

46.0892

5

SELF_MIGRATING

172184

10

3755.31

3762.66

3762.33

3

F

38645

120936

21.21

47.2098

5

SELF_MIGRATING

172178

10

3755.31

3773.71

3762.33

3

F

111080

120936

34.4271

47.2098

2

SELF_MIGRATING

172897

10

3762.33

3768.5

3762.33

3

F

3016

113676

43.5092

29.6387

1

SELF_MIGRATING

172179

10

3755.31

3772.11

3762.33

3

F

111080

11486

34.4463

44.2118

1

SELF_MIGRATING

172881

10

3762.33

3773.72

3762.33

3

F

111080

717

34.4463

17.0808

1

SELF_MIGRATING

172868

10

3762.33

3768.25

3762.33

3

F

111080

47236

34.4463

46.0892

4

SELF_MIGRATING

172189

10

3755.31

3781.92

3762.33

3

F

3016

95405

43.5092

58.1862

5

SELF_MIGRATING

172888

10

3762.33

3763.51

3762.33

3

F

38645

95405

21.21

58.1862

2

SELF_MIGRATING

172884

10

3762.33

3766.08

3762.33

3

F

65716

95405

37.7356

58.1862

3

SELF_MIGRATING

172887

10

3762.33

3763.07

3762.33

3

F

65716

47236

37.7548

46.0892

1

SELF_MIGRATING

172885

10

3762.33

3766.88

3762.33

3

F

65716

11486

37.7548

44.2118

3

SELF_MIGRATING

172896

10

3762.33

3763.24

3762.33

3

F

3016

47236

43.5092

46.1084

1

SELF_MIGRATING

172891

10

3762.33

3769.05

3762.33

3

F

38645

47236

21.21

46.1084

1

SELF_MIGRATING

172183

10

3755.31

3763.98

3762.33

3

F

38645

717

21.2292

17.0808

1

SELF_MIGRATING

172890

10

3762.33

3786.33

3762.33

3

F

38645

11486

21.2292

44.2118

4

SELF_MIGRATING

172893

10

3762.33

3775.59

3762.33

3

F

3016

11486

43.5092

44.2311

1

SELF_MIGRATING

172895

10

3762.33

3764.87

3762.33

3

F

3016

717

43.5284

17.0808

1

SELF_MIGRATING

172190

9

3755.31

3760.9

3762.33

3

F

202259

2323

20.2242

18.1876

1

BROKEUP

172191

9

3755.31

3757.87

3762.33

3

F

202259

28129

20.2242

44.1352

2

BROKEUP

172192

9

3755.31

3756.39

3762.33

3

F

202259

42308

20.2242

47.9411

1

BROKEUP

172193

9

3755.31

3758.84

3762.33

3

F

202259

60557

20.2242

57.4423

1

BROKEUP

172194

9

3755.31

3756.49

3762.33

3

F

202259

1674

20.2242

18.0379

1

BROKEUP

172196

9

3755.31

3755.86

3762.33

3

F

202259

183570

20.2242

43.1332

4

BROKEUP

172197

9

3755.31

3759.54

3762.33

3

F

135258

42308

39.594

47.9411

1

BROKEUP

172198

9

3755.31

3755.96

3762.33

3

F

135258

148216

39.594

48.9379

2

BROKEUP

172201

9

3755.31

3758.1

3762.33

3

F

126711

42308

39.5426

47.9411

1

BROKEUP

172202

9

3755.31

3759.2

3762.33

3

F

126711

2323

39.5426

18.1876

2

BROKEUP

172205

9

3755.31

3760.69

3762.33

3

F

119968

42308

21.1026

47.9411

1

BROKEUP

172207

9

3755.31

3755.82

3762.33

3

F

119968

28129

21.1026

44.1352

3

BROKEUP

172208

9

3755.31

3759.08

3762.33

3

F

119968

183570

21.1026

43.1332

1

BROKEUP

172209

9

3755.31

3756.58

3762.33

3

F

119968

46763

21.1026

40.6729

5

BROKEUP

172213

9

3755.31

3755.55

3762.33

3

F

113588

183570

30.5623

43.1332

1

BROKEUP

172214

9

3755.31

3758.2

3762.33

3

F

113588

42308

30.5623

47.9411

5

BROKEUP

172215

9

3755.31

3762.08

3762.33

3

F

111795

60557

18.2142

57.4423

1

BROKEUP

172216

9

3755.31

3759.91

3762.33

3

F

111795

42308

18.2142

47.9411

3

BROKEUP

172218

9

3755.31

3757.78

3762.33

3

F

111795

46763

18.2142

40.6729

3

BROKEUP

172219

9

3755.31

3757.94

3762.33

3

F

111795

2323

18.2142

18.1876

2

BROKEUP

172221

9

3755.31

3759.01

3762.33

3

F

111619

46763

29.3783

40.6729

1

BROKEUP

172222

9

3755.31

3755.64

3762.33

3

F

111619

1674

29.3783

18.0379

1

BROKEUP

172223

9

3755.31

3760.59

3762.33

3

F

111619

28129

29.3783

44.1352

1

BROKEUP

172224

9

3755.31

3757.9

3762.33

3

F

111619

148216

29.3783

48.9379

1

BROKEUP

172225

9

3755.31

3758.64

3762.33

3

F

111619

2323

29.3783

18.1876

1

BROKEUP

172226

9

3755.31

3757.09

3762.33

3

F

111278

46763

20.7778

40.6729

1

BROKEUP

172227

9

3755.31

3759.78

3762.33

3

F

111278

148216

20.7778

48.9379

2

BROKEUP

172229

9

3755.31

3759.28

3762.33

3

F

111278

1674

20.7778

18.0379

1

BROKEUP

172231

9

3755.31

3756.14

3762.33

3

F

111278

64561

20.7778

17.7342

1

BROKEUP

172232

9

3755.31

3760.99

3762.33

3

F

111278

183570

20.7778

43.1332

3

BROKEUP

172235

9

3755.31

3759.47

3762.33

3

F

90279

60557

22.2737

57.4423

1

BROKEUP

172236

9

3755.31

3761.98

3762.33

3

F

90279

2323

22.2737

18.1876

1

BROKEUP

172239

9

3755.31

3756.71

3762.33

3

F

71348

1674

40.8685

18.0379

2

BROKEUP

172241

9

3755.31

3761.49

3762.33

3

F

71348

60557

40.8685

57.4423

4

BROKEUP

172242

9

3755.31

3756.98

3762.33

3

F

71348

2323

40.8685

18.1876

1

BROKEUP

172247

9

3755.31

3756.83

3762.33

3

F

37611

42308

35.0683

47.9411

3

BROKEUP

172249

9

3755.31

3756.49

3762.33

3

F

37611

28129

35.0683

44.1352

1

BROKEUP
ReportRelationshipCensus

The relationship census report (ReportRelationshipCensus.csv) is a CSV-formatted report that extracts relationship numbers for each person during each taking of the census. The census is a one day event collecting data for that person as of that day.

Configuration

To generate this report, the following parameters must be configured in the custom_reports.json file:

Parameter

Data type

Min

Max

Default

Description

Report_File_Name

string

NA

NA

ReportRelationshipCensus.csv

Use this parameter to designate a custom file name, if desired.

Start_Year

float

0

FLT_MAX

0

Simulation time in years to start collecting data.

End_Year

float

0

FLT_MAX

FLT_MAX

Simulation time in years to stop collecting data.

Reporting_Interval_Years

float

0

100

1

Years between census-taking.

 
{
    "Reports": [
        {
            "class": "ReportRelationshipCensus",
            "Report_File_Name": "MyCensusReport.csv",
            "Start_Year": 2020,
            "End_Year": 2050,
            "Reporting_Interval_Years": 1
        }
    ],
    "Use_Defaults": 1
}
Output file data

The output report will contain the following information.

Data columns

Parameter

Data type

Description

Year

float

Current time of the census in years.

NodeID

integer

The External ID of the node that the data is being collected for.

IndividualID

integer

The unique ID of the person whose information is being collected.

Gender

string

The gender of the individual. Possible values are “M” or “F.”

AgeYears

float

The age in years of the person whose information is being collected.

IndividualProperties

string

A single string with the person’s properties. The string will have a format where a key and value are separated by colons and the key-value pairs are separated by semi-colons. For example: KeyA:ValueA1;KeyB:ValueB1;KeyC:ValueC1.

NumRels_Last6Months_TRANSITORY

integer

The number of transitory relationships that the person has started in the last 6 months.

NumRels_Last6Months_INFORMAL

integer

The number of informal relationships that the person has started in the last 6 months.

NumRels_Last6Months_MARITAL

integer

The number of marital relationships that the person has started in the last 6 months.

NumRels_Last6Months_COMMERCIAL

integer

The number of commercial relationships that the person has started in the last 6 months.

NumRels_Active_TRANSITORY

integer

The number of transitory relationships the person has on the day of the census.

NumRels_Active_INFORMAL

integer

The number of active informal relationships the person has on the day of the census.

NumRels_Active_MARITAL

integer

The number of active marital relationships the person has on the day of the census.

NumRels_Active_COMMERCIAL

integer

The number of active commercial relationships the person has on the day of the census.

NumRels_Last12Months_TRANSITORY

integer

The number of transitory relationships that the person has started in the last 12 months.

NumRels_Last12Months_INFORMAL

integer

The number of informal relationships that the person has started in the last 12 months.

NumRels_Last12Months_MARITAL

integer

The number of marital relationships that the person has started in the last 12 months.

NumRels_Last12Months_COMMERCIAL

integer

The number of commercial relationships that the person has started in the last 12 months.

NumUniquePartners_Last-3-Months_TRANSITORY

integer

The number of different people that this person has had a transitory relationship in the last 3 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-3-Months_INFORMAL

integer

The number of different people that this person has had a informal relationship in the last 3 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-3-Months_MARITAL

integer

The number of different people that this person has had a marital relationship in the last 3 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-3-Months_COMMERCIAL

integer

The number of different people that this person has had a commercial relationship in the last 3 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-6-Months_TRANSITORY

integer

The number of different people that this person has had a transitory relationship in the last 6 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-6-Months_INFORMAL

integer

The number of different people that this person has had a informal relationship in the last 6 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-6-Months_MARITAL

integer

The number of different people that this person has had a marital relationship in the last 6 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-6-Months_COMMERCIAL

integer

The number of different people that this person has had a commercial relationship in the last 6 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-9-Months_TRANSITORY

integer

The number of different people that this person has had a transitory relationship in the last 9 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-9-Months_INFORMAL

integer

The number of different people that this person has had a informal relationship in the last 9 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-9-Months_MARITAL

integer

The number of different people that this person has had a marital relationship in the last 9 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-9-Months_COMMERCIAL

integer

The number of different people that this person has had a commercial relationship in the last 9 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-12-Months_TRANSITORY

integer

The number of different people that this person has had a transitory relationship in the last 12 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-12-Months_INFORMAL

integer

The number of different people that this person has had a informal relationship in the last 12 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-12-Months_MARITAL

integer

The number of different people that this person has had a marital relationship in the last 12 months. This is different than just the number of relationships because one could start and stop relationships with the same person.

NumUniquePartners_Last-12-Months_COMMERCIAL

integer

The number of different people that this person has had a commercial relationship in the last 12 months. This is different than just the number of relationships because one could start and stop relationships with the same person.
Example

The following is an example of a ReportRelationshipCensus.csv file.

Year

NodeID

IndividualID

Gender

AgeYears

IndividualProperties

NumRels_Last6Months_TRANSITORY

NumRels_Last6Months_INFORMAL

NumRels_Last6Months_MARITAL

NumRels_Last6Months_COMMERCIAL

NumRels_Active_TRANSITORY

NumRels_Active_INFORMAL

NumRels_Active_MARITAL

NumRels_Active_COMMERCIAL

NumRels_Last12Months_TRANSITORY

NumRels_Last12Months_INFORMAL

NumRels_Last12Months_MARITAL

NumRels_Last12Months_COMMERCIAL

NumUniquePartners_Last-3-Months_TRANSITORY

NumUniquePartners_Last-3-Months_INFORMAL

NumUniquePartners_Last-3-Months_MARITAL

NumUniquePartners_Last-3-Months_COMMERCIAL

NumUniquePartners_Last-6-Months_TRANSITORY

NumUniquePartners_Last-6-Months_INFORMAL

NumUniquePartners_Last-6-Months_MARITAL

NumUniquePartners_Last-6-Months_COMMERCIAL

NumUniquePartners_Last-9-Months_TRANSITORY

NumUniquePartners_Last-9-Months_INFORMAL

NumUniquePartners_Last-9-Months_MARITAL

NumUniquePartners_Last-9-Months_COMMERCIAL

NumUniquePartners_Last-12-Months_TRANSITORY

NumUniquePartners_Last-12-Months_INFORMAL

NumUniquePartners_Last-12-Months_MARITAL

NumUniquePartners_Last-12-Months_COMMERCIAL

1962

1

2

F

12.0359

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1962

1

3

F

20.6407

Risk:LOW

0

0

7

0

0

0

0

0

0

0

9

0

0

0

1

0

0

0

7

0

0

0

9

0

0

0

9

0

1962

1

4

F

62.176

Risk:LOW

0

0

14

0

0

0

0

0

0

0

28

0

0

0

7

0

0

0

13

0

0

0

19

0

0

0

23

0

1962

1

5

F

47.2766

Risk:LOW

0

0

31

0

0

0

0

0

0

0

52

0

0

0

18

0

0

0

29

0

0

0

35

0

0

0

43

0

1962

1

6

F

54.0897

Risk:LOW

0

0

13

0

0

0

0

0

0

0

30

0

0

0

5

0

0

0

11

0

0

0

20

0

0

0

21

0

1962

1

7

M

14.3385

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1962

1

8

F

8.85676

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1962

1

9

M

5.39688

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1962

1

10

M

24.2559

Risk:LOW

0

0

4

0

0

0

0

0

0

0

12

0

0

0

1

0

0

0

4

0

0

0

8

0

0

0

12

0

1963

1

2

F

13.0359

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963

1

3

F

21.6407

Risk:LOW

0

0

8

0

0

0

0

0

0

0

12

0

0

0

4

0

0

0

8

0

0

0

8

0

0

0

12

0

1963

1

4

F

63.176

Risk:LOW

0

0

2

0

0

0

0

0

0

0

15

0

0

0

0

0

0

0

2

0

0

0

6

0

0

0

15

0

1963

1

5

F

48.2766

Risk:LOW

0

0

18

0

0

0

0

0

0

0

46

0

0

0

7

0

0

0

14

0

0

0

24

0

0

0

35

0

1963

1

6

F

55.0897

Risk:LOW

0

0

16

0

0

0

1

0

0

0

37

0

0

0

10

0

0

0

17

0

0

0

24

0

0

0

29

0

1963

1

7

M

15.3385

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963

1

8

F

9.85676

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963

1

9

M

6.39688

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1963

1

10

M

25.2559

Risk:LOW

0

0

0

0

0

0

0

0

0

0

1

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1

0

1964

1

2

F

14.0359

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1964

1

3

F

22.6407

Risk:LOW

0

0

11

0

0

0

0

0

0

0

18

0

0

0

8

0

0

0

12

0

0

0

16

0

0

0

17

0

1964

1

4

F

64.176

Risk:LOW

0

0

3

0

0

0

0

0

0

0

5

0

0

0

1

0

0

0

3

0

0

0

3

0

0

0

4

0

1964

1

5

F

49.2766

Risk:LOW

0

0

14

0

0

0

1

0

0

0

37

0

0

0

8

0

0

0

15

0

0

0

25

0

0

0

29

0

1964

1

6

F

56.0897

Risk:LOW

0

0

14

0

0

0

0

0

0

0

22

0

0

0

10

0

0

0

15

0

0

0

17

0

0

0

18

0

1964

1

7

M

16.3385

Risk:LOW

0

0

2

0

0

0

1

0

0

0

2

0

0

0

2

0

0

0

2

0

0

0

2

0

0

0

2

0

1964

1

8

F

10.8568

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1964

1

9

M

7.39688

Risk:LOW

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

0

1964

1

10

M

26.2559

Risk:LOW

0

0

3

0

0

0

0

0

0

0

8

0

0

0

1

0

0

0

3

0

0

0

6

0

0

0

8

0
RelationshipConsummated

The coital act report (RelationshipConsummated.csv) provides detailed information about each coital act that occurs during the simulation. The report includes unique identifiers for each coital act and relationship; the relationship type, number of acts, whether a condom was used, and whether transmission occurred; and detailed information about each participant, including age, gender, infection status, circumcision status, co-infection status, and treatment status. Each participant in a relationship is referred to as either participant “A” or participant “B”.

One row of data is returned per coital act, and results are ordered on a per-relationship basis. Note: if a person is engaged in coital acts in multiple relationships during a time step, the order of those acts is unknown, only in which relationship they occurred. Additionally, if a person gets infected during a time step, they cannot re-transmit that infection during the same time step. The report does record during which coital act transmission occurred.

If an uninfected person has coital acts with multiple infected partners during a time step, all acts with the possibility of transmission are randomly ordered, so that the person has an equal chance of getting infected from any one of their partners. The probability of transmission from any one of these coital acts is still determined by the simulation parameters (number of acts, acquisition multipliers, etc.)

Configuration

To generate the report, the following parameters must be configured in the config.json file:

Parameter

Data type

Min

Max

Default

Description

Report_Coital_Acts

boolean

NA

NA

0

Set this to 1 to generate the report.

Report_Coital_Acts_Start_Year

float

1900

2200

1900

Simulation time in years to start collecting data.

Report_Coital_Acts_End_Year

float

1900

2200

2200

Simulation time in years to stop collecting data.

Report_Coital_Acts_Node_IDs_Of_Interest

float

0

2.14748e+09

[]

Data will be collected for the nodes in this list.

Report_Coital_Acts_Min_Age_Years

float

0

9.3228e+35

0

The age that of one of the partners must be greater than or equal to for the coital act to be reported.

Report_Coital_Acts_Max_Age_Years

float

0

9.3228e+35

9.3228e+35

The age that of one of the partners must be less than or equal to for the coital act to be reported.

Report_Coital_Acts_Must_Have_IP_Key_Value

string

NA

NA

""

A Key:Value pair that one of the partners must have for the coital act to be reported. Empty string means don’t look at individual properties. For more information, see Individual and node properties.

Report_Coital_Acts_Must_Have_Intervention

string

NA

NA

""

The name of an intervention that the one of the partners must have in order for the coital act to be reported. Empty string means don’t look at the interventions. For more information, see Individual-level interventions.

Report_Coital_Acts_Relationship_Type

enum

NA

NA

NA

If not NA, data will only be collected on coital acts in relationships of this type. Possible values are:

  • TRANSITORY

  • INFORMAL

  • MARITAL

  • COMMERCIAL

Report_Coital_Acts_Has_Intervention_With_Name

string

NA

NA

""

The name of an intervention that the one of the partners must have in order for the coital act to be reported. Empty string means don’t look at the interventions. For more information, see Individual-level interventions.

Report_Coital_Acts_Individual_Properties

array of strings

NA

NA

[]

A list of individual property (IP) keys that will be included in the report as applicable to each partner. One column will be added to the report for each partner, for each key in the list. Specify the IP keys by adding an IndividualProperties parameter in the demographics file. See Individual and node properties for details on setting individual properties.

Report_Coital_Acts_Partners_With_IP_Key_Value

array of strings

NA

NA

[]

A list of Key:Value pairs. Two columns will be added to the report for each Key:Value pair listed, one for each partner, indicating the number of that individual’s partners for which the Key:Value pair applies.

 
{
    "Report_Coital_Acts": 1,
    "Report_Coital_Acts_Start_Year": 2000,
    "Report_Coital_Acts_End_Year": 2050,
    "Report_Coital_Acts_Node_IDs_Of_Interest": [ 1, 2, 3 ],
    "Report_Coital_Acts_Min_Age_Years": 30,
    "Report_Coital_Acts_Max_Age_Years": 90,
    "Report_Coital_Acts_Must_Have_IP_Key_Value": "Risk:LOW",
    "Report_Coital_Acts_Must_Have_Intervention": "",
    "Report_Coital_Acts_Relationship_Type": "MARITAL",
    "Report_Coital_Acts_Has_Intervention_With_Name": "",
    "Report_Coital_Acts_Individual_Properties": [],
    "Report_Coital_Acts_Partners_With_IP_Key_Value": ["Risk:HIGH"],
}
Output file data

The output report will contain the following information.

Data channel

Data type

Description

Time

float

The simulation time (in days) when the coital act occurred.

Year

float

The simulation time (in calendar years) when the coital act occurred.

Node_ID

integer

The numerical identifier of the node as defined in the demographics. See Demographics parameters for details on configuring the NodeID values.

Coital_Act_ID

integer

The unique identifier for the coital act.

Rel_ID

integer

The unique identifier for the relationship, different from the ID of the participants or the coital act.

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

integer

The type of relationship between individuals A and B. Values for 0-3 as indicated in the header.

Is_rel_outside_PFA

boolean

Indicates whether or not the relationship was created by the normal process using the Pair Forming Algorithm (PFA), where “F” indicates the relationship was created using the PFA, and “T” indicates the relationship was created using the StartNewRelationship intervention.

<A or B>_ID

integer

The unique numerical identifier for the individual. There is a column for each partner.

<A or B>_gender

enum

The gender of the individual (MALE or FEMALE). There is a column for each partner.

<A or B>_Age

float

The age (in years) of the individual. There is a column for each partner.

<A or B>_Is_Infected

boolean

Indicates whether or not the individual is infected: 0 for not infected, 1 for infected. There is a column for each partner.

Did_Use_Condom

boolean

Indicates if a condom was used for the coital act: 0 for no condom used, 1 for a condom was used.

Risk_Multiplier

float

Multiplier for the risk of transmission from the coital act. Determined by STI co-infection of either partner (via ModifyStiCoInfectionStatus). The multiplier starts as the maximum value of the STI_Coinfection_Acquisition_Multiplier and STI_Coinfection_Transmission_Multiplier parameters. This maximum is then multiplied by the coital act risk factors from each partner, if they have the CoitalActRiskFactor intervention distributed. See Scalars and multipliers and Individual-level interventions for more information.

Transmission_Multiplier

float

Multiplier for disease transmission risk from the infected partner. Determined by the transmitter’s infectiousness, and any immunity-modifying interventions. See Individual-level interventions for more information.

Acquisition_Multiplier

float

Multiplier for disease acquisition risk for the uninfected partner. Determined by:

  • The MaleCircumcision intervention, if the uninfected partner is male

  • The Male_To_Female_Relative_Infectivity_Ages and Male_To_Female_Relative_Infectivity_Multipliers campaign parameters, if the uninfected partner is female, and

  • Any acquisition-blocking interventions

See Campaign parameters and Individual-level interventions for more information.

Infection_Was_Transmitted

boolean

Indicates whether or not the uninfected partner became infected due to this coital act: 0 if the uninfected partner was not infected, 1 if they were.

<A or B>_Num_Current_Rels

integer

The total number of active relationships the individual is currently in. There is a column for each partner.

<A or B>_Is_Circumcised

boolean

Indicates whether or not the individual is circumcised (only applicable to males): 0 for not circumcised (and females), 1 for circumcised. There is a column for each partner

<A or B>_Has_Coinfection

boolean

Indicates whether or not the individual has an STI co-infection, as determined by the ModifyStiCoInfectionStatus intervention: 0 if they do not have an STI co-infection, 1 if they do have an STI co-infection. There is a column for each partner. Note: this is only included for HIV simulations.

<A or B>_HIV_Infection_Stage

enum

Indicates the stage of HIV infection for the receiving individual. Possible values are:

  • 0 = Uninfected

  • 1 = Untreated acute HIV infection

  • 2 = Untreated latent HIV infection

  • 3 = Untreated late/AIDS stage

  • 4 = On ART

There is a column for each partner. Note: this is only included for HIV simulations.

<A or B>_Is_On_ART

boolean

Indicates whether or not the individual is on ART: 0 if they are not on ART, 1 if they are currently receiving ART. There is a column for each partner. Note: this is only included for HIV simulations.

<A or B>_IP=<IP Key>

string

For each IP Key listed in Report_Coital_Acts_Individual_Properties, a column will be added to the report for each partner, indicating the value of that IP Key for that partner.

<A or B>_PartersWith_IP=<IP Key:Value>

integer

For each IP Key:Value pair listed in Report_Coital_Acts_Partners_With_IP_Key_Value, a column will be added to the report for each partner, indicating the number of their partners for whom that IP Key:Value pair applies.
Example

The following is an example of a RelationshipConsummated.csv report:

Time

Year

Node_ID

Coital_Act_ID

Rel_ID

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

Is_rel_outside_PFA

A_ID

B_ID

A_Gender

B_Gender

A_Age

B_Age

A_Is_Infected

B_Is_Infected

Did_Use_Condom

Risk_Multiplier

Transmission_Multiplier

Acquisition_Multiplier

Infection_Was_Transmitted

A_Num_Current_Rels

B_Num_Current_Rels

A_Is_Circumcised

B_Is_Circumcised

A_Has_CoInfection

B_Has_CoInfection

A_HIV_Infection_Stage

B_HIV_Infection_Stage

A_Is_On_ART

B_Is_On_ART

1380

1964.28

1

264665

2080

2

F

1059

422

MALE

FEMALE

16.0964

14.9642

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1380

1964.28

1

264666

2080

2

F

1059

422

MALE

FEMALE

16.0964

14.9642

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1380

1964.28

1

264667

2080

2

F

1059

422

MALE

FEMALE

16.0964

14.9642

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1380

1964.28

1

264668

2080

2

F

1059

422

MALE

FEMALE

16.0964

14.9642

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1380

1964.28

1

264669

2080

2

F

1059

422

MALE

FEMALE

16.0964

14.9642

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1380

1964.28

1

264673

3167

1

F

1060

786

MALE

FEMALE

32.523

23.992

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1380

1964.28

1

264674

3167

1

F

1060

786

MALE

FEMALE

32.523

23.992

0

0

1

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1380

1964.28

1

264675

3167

1

F

1060

786

MALE

FEMALE

32.523

23.992

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1380

1964.28

1

264676

3167

1

F

1060

786

MALE

FEMALE

32.523

23.992

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1380

1964.28

1

264677

3167

1

F

1060

786

MALE

FEMALE

32.523

23.992

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1380

1964.28

1

264702

2462

0

F

1072

1491

MALE

FEMALE

19.3131

12.3697

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264703

2462

0

F

1072

1491

MALE

FEMALE

19.3131

12.3697

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264704

2462

0

F

1072

1491

MALE

FEMALE

19.3131

12.3697

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264705

2462

0

F

1072

1491

MALE

FEMALE

19.3131

12.3697

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264706

2462

0

F

1072

1491

MALE

FEMALE

19.3131

12.3697

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264707

3008

2

F

1072

492

MALE

FEMALE

19.3131

12.0558

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264708

3008

2

F

1072

492

MALE

FEMALE

19.3131

12.0558

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264709

3008

2

F

1072

492

MALE

FEMALE

19.3131

12.0558

1

1

0

1

0.001

1

1

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264710

3008

2

F

1072

492

MALE

FEMALE

19.3131

12.0558

1

1

0

0

0

0

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264711

3008

2

F

1072

492

MALE

FEMALE

19.3131

12.0558

1

1

0

0

0

0

0

3

4

1

0

0

0

2

1

0

0

1380

1964.28

1

264752

768

0

F

1090

1715

MALE

FEMALE

24.8718

32.9547

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264753

768

0

F

1090

1715

MALE

FEMALE

24.8718

32.9547

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264754

768

0

F

1090

1715

MALE

FEMALE

24.8718

32.9547

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264755

768

0

F

1090

1715

MALE

FEMALE

24.8718

32.9547

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264756

768

0

F

1090

1715

MALE

FEMALE

24.8718

32.9547

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264757

2089

2

F

1090

1267

MALE

FEMALE

24.8718

23.2888

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1380

1964.28

1

264758

2089

2

F

1090

1267

MALE

FEMALE

24.8718

23.2888

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269710

2080

2

F

1059

422

MALE

FEMALE

16.1786

15.0464

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1410

1964.36

1

269711

2080

2

F

1059

422

MALE

FEMALE

16.1786

15.0464

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1410

1964.36

1

269712

2080

2

F

1059

422

MALE

FEMALE

16.1786

15.0464

0

1

0

1

0.001

0.4

0

1

4

1

0

0

0

1

2

0

0

1410

1964.36

1

269722

3167

1

F

1060

786

MALE

FEMALE

32.6052

24.0742

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1410

1964.36

1

269723

3167

1

F

1060

786

MALE

FEMALE

32.6052

24.0742

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1410

1964.36

1

269724

3167

1

F

1060

786

MALE

FEMALE

32.6052

24.0742

0

0

0

0

0

0

0

3

4

0

0

0

0

1

1

0

0

1410

1964.36

1

269748

2462

0

F

1072

1491

MALE

FEMALE

19.3953

12.4519

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1410

1964.36

1

269749

2462

0

F

1072

1491

MALE

FEMALE

19.3953

12.4519

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1410

1964.36

1

269750

2462

0

F

1072

1491

MALE

FEMALE

19.3953

12.4519

1

0

0

1

0.001

1

0

3

4

1

0

0

0

2

1

0

0

1410

1964.36

1

269751

3008

2

F

1072

492

MALE

FEMALE

19.3953

12.138

1

1

1

0

0

0

0

3

4

1

0

0

0

2

1

0

0

1410

1964.36

1

269752

3008

2

F

1072

492

MALE

FEMALE

19.3953

12.138

1

1

0

0

0

0

0

3

4

1

0

0

0

2

1

0

0

1410

1964.36

1

269805

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269806

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269807

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269808

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269809

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269810

768

0

F

1090

1715

MALE

FEMALE

24.954

33.0369

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269811

2089

2

F

1090

1267

MALE

FEMALE

24.954

23.3709

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269812

2089

2

F

1090

1267

MALE

FEMALE

24.954

23.3709

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269813

2089

2

F

1090

1267

MALE

FEMALE

24.954

23.3709

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0

1410

1964.36

1

269814

2089

2

F

1090

1267

MALE

FEMALE

24.954

23.3709

1

1

0

0

0

0

0

3

4

1

0

0

0

2

2

0

0
ReportRelationshipMigrationTracking

The relationship migration tracking report (ReportRelationshipMigrationTracking.csv) provides information about the relationships a person has when they are migrating. It will give information when they are leaving and entering a node. When leaving a node, the information will be about the status of the relationships just before they leave. When entering the new node, the information will be about the relationships that have been updated. For example, a person could leave with a relationship paused, find their partner in the new node, and get their relationship back to normal. This helps to know about how the status of the relationships have changed—migrated, paused, or terminated.

The person initiating a migration event will first have their relationships listed in the state before migrating starts. If a partner is asked to migrate with them, then that partner’s relationships will also be listed. When the people are immigrating into the new node, the list of relationships that are continuing in the new node will be listed. Any migrated partner should only have the relationship with the partner initiating migration. Their other relationships will have been terminated.

Configuration

To generate this report, the following parameters must be configured in the custom_reports.json file:

Parameter

Data type

Min

Max

Default

Description

Filename_Suffix

string

NA

NA

""

Augments the filename of the report. If multiple reports are being generated, this allows you to distinguish among the multiple reports.

Start_Year

float

1900

2200

1900

Simulation time in years to start collecting data, including fractions of years. For example, 2025.0 means January 1st, 2025.

End_Year

float

1900

2200

2200

Simulation time in years to stop collecting data, including fractions of years. For example, 2025.0 means January 1st, 2025.

Node_IDs_Of_Interest

array

0

2.14748e+09

[]

Data will be collected for the nodes in this list. Leave the array empty (default value) to include all nodes.

Min_Age_Years

float

0

9.3228e+35

0

Minimum age in years of people to collect data on.

Max_Age_Years

float

0

9.3228e+35

9.3228e+35

Maximum age in years of people to collect data on.

Must_Have_IP_Key_Value

string

NA

NA

""

A Key:Value pair that the individual must have in order to be included. Leave the string empty (default value) to not look at individual properties. For more information, see Individual and node properties.

Must_Have_Intervention

string

NA

NA

""

The name of an intervention that the person must have in order to be included. Leave the string empty (default value) to not look at the interventions. For more information, see Individual-level interventions.

 
{
    "Reports": [
        {
            "Filename_Suffix": "example",
            "Start_Year": 1900,
            "End_Year": 2200,
            "Node_IDs_Of_Interest":[ 1, 2, 3 ],
            "Min_Age_Years": 20,
            "Max_Age_Years": 90,
            "Must_Have_IP_Key_Value": "",
            "Must_Have_Intervention": "",
            "class": "ReportRelationshipMigrationTracking"
        }
    ],
    "Use_Defaults": 1
}
Output file data

The output report will contain the following information.

Data columns

Parameter

Data type

Description

Time

float

The simulation time of the migration event—emigrating or immigrating.

Year

float

The simulation time of the migration event in years.

IndividualID

integer

The unique ID of the migrating individual.

AgeYears

float

The age in years of the migrating individual.

Gender

string

The gender of the individual. Possible values are “M” or “F.”

From_NodeID

string

The external ID of the node the individual is moving from.

To_NodeID

string

The external ID of the node the individual is moving to, as defined in the demographics. This can be zero when the person has immigrated into the destination node.

MigrationType

enum

The type of migration that is occurring at the time of the triggering event (see the Event column). If the triggering event is SimulationEnd, possible MigrationType values are either “home” or “away,” indicating if the individual was in their home node or not when the simulation ended. For all other events, the possible values are: air, local, sea, or regional.

Event

enum

The event triggering the migration information to be reported. Possible values are: STIPreEmigrating, STIPostImmigrating, NonDiseaseDeaths, DiseaseDeaths. Emigrating means the individual is moving, SimulationEnd means the simulation has finished. One row of data will be recorded for each event.

IsInfected

boolean

Describes whether or not the individual is infected: 0 for not infected, 1 for infected.

Rel_ID

integer

The unique ID of the relationship that is migrating.

NumCoitalActs

integer

The total number of coital acts this couple has had within this relationship up to this time.

IsDiscordant

boolean

Describes whether or not both individuals in a relationship are infected: 0 indicates that the partners are either both infected or both uninfected, 1 indicates that one of the partners is infected and the other is not.

HasMigrated

boolean

0 indicates false, 1 indicates that the person identified by IndividualID has completed migrating. Will be true when the event is STIPostImmigrating.

RelationshipType

enum

The type of relationship whose information is being added to the report. Options are: TRANSITORY, INFORMAL, MARITAL, COMMERCIAL.

RelationshipState

enum

The state of the relationship. Possible values are:

NORMAL

Both partners are in the same node and can have coital acts.

MIGRATING

The partners are migrating together to a new node.

PAUSED

One of the partners is not in the same node so the couple will pause their coital acts.

TERMINATED

This is when the relationship ends. This value is unlikely to be seen in this report.

PartnerID

integer

The unique ID of the partner in the relationship with that of IndividualID.

Male_NodeID

integer

The node that the male of the relationship is in. If the value is zero, then IndividualID is a female and the male’s location is unknown. The relationship will be in the PAUSE state.

Female_NodeID

integer

The node that the female of the relationship is in. If the value is zero, then IndividualID is a male and the female’s location is unknown. The relationship will be in the PAUSE state.
Example

The following is an example of a ReportRelationshipMigrationTracking.csv file.

Time

Year

IndividualID

AgeYears

Gender

From_NodeID

To_NodeID

MigrationType

Event

IsInfected

Rel_ID

NumCoitalActs

IsDiscordant

HasMigrated

RelationshipType

RelationshipState

PartnerID

Male_NodeID

Female_NodeID

1278

1964

267

52.5321

F

4

2

local

STIPreEmigrating

0

84

72

0

0

MARITAL

PAUSED

101

0

4

1278

1964

267

52.5321

F

2

0

N/A

STIPostImmigrating

0

84

72

0

0

MARITAL

NORMAL

101

2

2

1279

1964

238

41.2518

F

1

2

local

STIPreEmigrating

0

91

130

0

0

INFORMAL

PAUSED

263

0

1

1279

1964

238

41.2518

F

2

0

N/A

STIPostImmigrating

0

91

130

0

0

INFORMAL

PAUSED

263

0

2

1280

1964.01

71

41.5481

M

4

2

local

STIPreEmigrating

0

106

35

0

0

MARITAL

PAUSED

255

4

0

1280

1964.01

202

36.6187

M

1

4

local

STIPreEmigrating

0

166

21

0

0

TRANSITORY

PAUSED

58

1

0

1280

1964.01

202

36.6187

M

4

0

N/A

STIPostImmigrating

0

166

21

0

0

TRANSITORY

PAUSED

58

4

0

1280

1964.01

71

41.5481

M

2

0

N/A

STIPostImmigrating

0

106

35

0

0

MARITAL

NORMAL

255

2

2

1281

1964.01

316

32.6281

F

4

3

local

STIPreEmigrating

0

154

47

0

0

MARITAL

PAUSED

20

0

4

1281

1964.01

129

53.1052

F

2

4

local

STIPreEmigrating

0

62

141

0

0

MARITAL

PAUSED

249

0

2

1281

1964.01

129

53.1052

F

4

0

N/A

STIPostImmigrating

0

62

141

0

0

MARITAL

PAUSED

249

0

4

1281

1964.01

316

32.6281

F

3

0

N/A

STIPostImmigrating

0

154

47

0

0

MARITAL

PAUSED

20

0

3

1282

1964.01

164

43.9009

F

2

3

local

STIPreEmigrating

0

44

66

0

0

MARITAL

NORMAL

248

2

2

1282

1964.01

164

43.9009

F

3

0

N/A

STIPostImmigrating

0

44

66

0

0

MARITAL

PAUSED

248

0

3

1283

1964.02

26

39.4271

F

3

1

local

STIPreEmigrating

0

130

64

0

0

MARITAL

PAUSED

187

0

3

1283

1964.02

148

31.3444

M

2

3

local

STIPreEmigrating

0

116

48

0

0

INFORMAL

NORMAL

63

2

2

1283

1964.02

148

31.3444

M

3

0

N/A

STIPostImmigrating

0

116

48

0

0

INFORMAL

PAUSED

63

3

0

1283

1964.02

26

39.4271

F

1

0

N/A

STIPostImmigrating

0

130

64

0

0

MARITAL

PAUSED

187

0

1

1284

1964.02

238

41.2654

F

2

1

local

STIPreEmigrating

0

91

130

0

0

INFORMAL

PAUSED

263

0

2

1284

1964.02

35

30.2736

F

1

2

local

STIPreEmigrating

0

165

9

0

0

INFORMAL

PAUSED

117

0

1

1284

1964.02

35

30.2736

F

2

0

N/A

STIPostImmigrating

0

165

9

0

0

INFORMAL

PAUSED

117

0

2

1284

1964.02

238

41.2654

F

1

0

N/A

STIPostImmigrating

0

91

130

0

0

INFORMAL

PAUSED

263

0

1

1285

1964.02

129

53.1161

F

4

3

local

STIPreEmigrating

0

62

141

0

0

MARITAL

PAUSED

249

0

4

1285

1964.02

119

43.9805

F

4

2

local

STIPreEmigrating

0

68

98

0

0

MARITAL

PAUSED

163

0

4

1285

1964.02

119

43.9805

F

2

0

N/A

STIPostImmigrating

0

68

98

0

0

MARITAL

PAUSED

163

0

2

1285

1964.02

129

53.1161

F

3

0

N/A

STIPostImmigrating

0

62

141

0

0

MARITAL

NORMAL

249

3

3

1286

1964.02

168

38.5155

F

4

3

local

STIPreEmigrating

0

18

86

0

0

MARITAL

PAUSED

160

0

4

1286

1964.02

168

38.5155

F

3

0

N/A

STIPostImmigrating

0

18

86

0

0

MARITAL

NORMAL

160

3

3

1287

1964.03

248

50.4619

M

2

3

local

STIPreEmigrating

0

44

66

0

0

MARITAL

PAUSED

164

2

0

1287

1964.03

248

50.4619

M

3

0

N/A

STIPostImmigrating

0

44

66

0

0

MARITAL

NORMAL

164

3

3

1288

1964.03

277

31.8828

M

4

2

local

STIPreEmigrating

0

160

30

0

0

INFORMAL

NORMAL

237

4

4

1288

1964.03

67

52.7351

F

2

1

local

STIPreEmigrating

0

50

53

0

0

MARITAL

PAUSED

89

0

2

1288

1964.03

294

42.8007

F

1

4

local

STIPreEmigrating

0

129

101

0

0

MARITAL

NORMAL

190

1

1

1288

1964.03

294

42.8007

F

4

0

N/A

STIPostImmigrating

0

129

101

0

0

MARITAL

PAUSED

190

0

4

1288

1964.03

67

52.7351

F

1

0

N/A

STIPostImmigrating

0

50

53

0

0

MARITAL

PAUSED

89

0

1

1288

1964.03

277

31.8828

M

2

0

N/A

STIPostImmigrating

0

160

30

0

0

INFORMAL

PAUSED

237

2

0

1289

1964.03

125

35.7124

F

4

1

local

STIPreEmigrating

0

70

120

0

0

MARITAL

PAUSED

109

0

4

1289

1964.03

125

35.7124

F

1

0

N/A

STIPostImmigrating

0

70

120

0

0

MARITAL

NORMAL

109

1

1
RelationshipStart

The relationship formation report (RelationshipStart.csv) provides information about each relationship and its members, evaluated at the time of relationship formation. The report includes the relationship type, start time, scheduled end time, and detailed information about each participant: ID, gender, age, infection status, circumcision status for males, co-infections, number of relationships (active, recent, lifetime), and individual properties. The male in the relationship is indicated on the report as participant “A”, and the female as participant “B”.

Configuration

To generate the report, the following parameters must be configured in the config.json file:

Parameter

Data type

Min

Max

Default

Description

Report_Relationship_Start

boolean

NA

NA

0

Set this to 1 to generate the report.

Report_Relationship_Start_Start_Year

float

1900

2200

1900

Simulation time in years to start collecting data.

Report_Relationship_Start_End_Year

float

1900

2200

2200

Simulation time in years to stop collecting data.

Report_Relationship_Start_Max_Age_Years

float

0

9.3228e+35

9.3228e+35

The age that of one of the partners must be less than or equal to for the relationship to be reported.

Report_Relationship_Start_Min_Age_Years

float

0

9.3228e+35

0

The age that of one of the partners must be greater than or equal to for the relationship to be reported.

Report_Relationship_Start_Node_IDs_Of_Interest

array

0

2.14748e+09

[]

Data will be collected for the nodes in this list.

Report_Relationship_Start_Include_HIV_Disease_Statistics

boolean

NA

NA

1

When set to 1, the report will include information on CD4 count, viral load, disease stage, HIV positivity, and HIV testing results for each partner in the relationship.

Report_Relationship_Start_Include_Other_Relationship_Statistics

boolean

NA

NA

1

When set to 1, the report will include information on the number of active and lifetime relationships of each type (Transitory, Informal, Marital, and Commercial) for each partner in the relationship, as well as total relationships in the past six month and total lifetime relationships. Additionally, a bitmask column will indicate which types of concurrent relationships are allowed; these are configured using the Concurrency_Configuration parameter in the demographics file—see Demographics parameters for more information.

Report_Relationship_Start_Individual_Properties

array of strings

NA

NA

[]

A list of individual property (IP) keys that will be included in the report as applicable to each partner at the start of the relationship. One column will be added to the report for each partner, for each key in the list. Specify the IP keys by adding an IndividualProperties parameter in the demographics file. See Individual and node properties for details on setting individual properties.

Report_Relationship_Start_Must_Have_IP_Key_Value

string

NA

NA

""

A Key:Value pair that one of the partners must have for the relationship to be reported. Empty string means don’t look at individual properties. For more information, see Individual and node properties.

Report_Relationship_Start_Must_Have_Intervention

string

NA

NA

""

The name of an intervention that the one of the partners must have in order for the relationship to be reported. Empty string means don’t look at the interventions. For more information, see Individual-level interventions.

 
{
    "Report_Relationship_Start": 1,
    "Report_Relationship_Start_Start_Year": 1900,
    "Report_Relationship_Start_End_Year": 2200,
    "Report_Relationship_Start_Max_Age_Years": 60,
    "Report_Relationship_Start_Min_Age_Years": 20,
    "Report_Relationship_Start_Node_IDs_Of_Interest": [ 1, 2, 3 ],
    "Report_Relationship_Start_Include_Other_Relationship_Statistics": 1,
    "Report_Relationship_Start_Individual_Properties": ["InterventionStatus"],
    "Report_Relationship_Start_Must_Have_IP_Key_Value": "Risk:HIGH",
    "Report_Relationship_Start_Must_Have_Intervention": "",
}
Output file data

The output report will contain the following information.

Data channel

Data type

Description

Rel_ID

integer

A unique identifier for the relationship, different from the IDs of the participants.

Rel_start_time

float

The time (in days) during the simulation when the relationship started.

Rel_scheduled_end_time

float

The time (in days) during the simulation when the relationship was scheduled to end. The duration of the relationship is dependent on the relationship type; configure by updating the Duration_Weibull_Heterogeneity and Duration_Weibull_Scale parameters in the demographics file. See Demographics parameters for details.

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

integer

The type of relationship between individuals A and B. Values for 0-3 as indicated in the header.

Is_rel_outside_PFA

character

Indicates whether or not the relationship was created by the normal process using the Pair Forming Algorithm (PFA), where “F” indicates the relationship was created using the PFA, and “T” indicates the relationship was created using the StartNewRelationship intervention.

Original_node_ID

integer

The ID of the node where the relationship started.

Current_node_ID

integer

The ID of the node where the participants currently reside.

<A or B>_ID

integer

The unique numerical identifier for the individual. There is a column for each partner.

<A or B>_is_infected

boolean

Indicates whether or not the individual is infected: 0 for not infected, 1 for infected. There is a column for each partner.

<A or B>_gender

boolean

The gender of the individual: 0 is for male, 1 is for female. There is a column for each partner.

<A or B>_age

float

The age of the individual in years. There is a column for each partner.

<A or B>_IP=<’IP_Key’>

depends on IP key

For each individual property key in the Report_Relationship_Start_Individual_Properties parameter list, a column will be added. The value will be the value for the IP key that this partner has at this time. There is a column for each partner. See Configuration for additional details on designating the IP keys.

<A or B>_total_num_active_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of active relationships the individual is currently in. There is a column for each partner.

<A or B>_num_active_TRANSITORY_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of transitory relationships the individual is currently in. There is a column for each partner.

<A or B>_num_active_INFORMAL_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of informal relationships the individual is currently in. There is a column for each partner.

<A or B>_num_active_MARITAL_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of marital relationships the individual is currently in. There is a column for each partner.

<A or B>_num_active_COMMERCIAL_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of commercial relationships the individual is currently in. There is a column for each partner.

<A or B>_num_lifetime_rels

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of relationships the individual has had during their lifetime. There is a column for each partner.

<A or B>_num_rels_last_6_mo

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating the total number of relationships the individual has had in the last six months. There is a column for each partner.

<A or B>_extra_relational_bitmask

integer

If the Report_Relationship_Start_Include_Other_Relationship_Statistics parameter is set to 1, this column will be included, indicating which types of relationships that individual is allowed to have when they have more than one active relationship. These values are configured using the Concurrency_Configuration parameter in the demographics file—see Demographics parameters for more information. These values can be updated when an individual migrates or has a value change in an individual property. The values are encoded in a 3-digit bitmask. In order, the digits correspond to Commercial (C), Marital (M), Informal (I), and Transitory (T) relationships. The following table provides example combinations:

Relationships allowed

Binary

Decimal Value

None

0000

0

T

0001

1

I

0010

2

I, T

0011

3

M

0100

4

M, T

0101

5

M, I

0110

6

M, I, T

0111

7

C

1000

8

C, T

1001

9

C, I

1010

10

C, I, T

1011

11

C, M

1100

12

C, M, T

1101

13

C, M, I

1110

14

C, M, I, T

1111

15

<A or B>_is_circumcised

boolean

Indicates whether or not the individual is circumcised: 0 for not circumcised, 1 for circumcised. There is a column for each partner.

<A or B>_has_STI_coinfection

boolean

Indicates whether or not the individual has an STI co-infection: 0 if they do not have an STI co-infection, 1 if they do have an STI co-infection. There is a column for each partner.

<A or B>_is_superspreader

boolean

Indicates whether or not the individual is a super-spreader: 0 if they are not a super-spreader, 1 if they are a super-spreader. This status is configured using the Probability_Person_Is_Behavioral_Super_Spreader parameter in the demographics file—see Demographics parameters for more information. There is a column for each partner.

<A or B>_CD4_count

float

If the Report_Relationship_Start_Include_HIV_Disease_Statistics parameter is set to 1, this column will be included, indicating the CD4 count for each partner. There is a column for each partner. Note: this is only included in HIV simulations.

<A or B>_viral_load

float

This channel is not currently supported. If the Include_HIV_Disease_Statistics parameter is set to 1, this column will be included, where -1 indicates that the partner is not infected, 1000 indicates that the partner is infected. There is a column for each partner. Note: this is only included in HIV simulations.

<A or B>_HIV_disease_stage

float

If the Report_Relationship_Start_Include_HIV_Disease_Statistics parameter is set to 1, this column will be included, indicating the stage of infection for each individual. There is a column for each partner. Possible values are:

  • 0 = Uninfected

  • 1 = Untreated acute HIV infection

  • 2 = Untreated latent HIV infection

  • 3 = Untreated late/AIDS stage

  • 4 = On ART

Note: this only included in HIV simulations.

<A or B>_HIV_Tested_Positive

boolean

If the Report_Relationship_Start_Include_HIV_Disease_Statistics parameter is set to 1, this column will be included, indicating whether or not the partner has ever tested positive for HIV using the results of the HIVRapidHIVDiagnostic campaign parameter. 0 indicates the partner has never tested positive, 1 indicates they have tested positive. See HIVRapidHIVDiagnostic for configuration details. There is a column for each partner. Note: this is only included in HIV simulations.

<A or B>_HIV_Received_Results

string

If the Include_HIV_Disease_Statistics parameter is set to 1, this column will be included, indicating the results received by the individual from the latest HIV test using the HIVRapidHIVDiagnostic campaign parameter. Possible values are:

UNKNOWN

Indicates that the individual did not receive their results.

NEGATIVE

Indicates that the most recent results were negative.

POSITIVE

Indicates that the most recent results were positive.

Whether or not the an individual receives their results is determined by the Probability_Received_Results campaign parameter—see HIVRapidHIVDiagnostic for configuration details. There is a column for each partner. Note: this is only included in HIV simulations.
Example

The following is an example of a RelationshipStart.csv report:

Rel_ID

Rel_start_time

Rel_scheduled_end_time

Rel_type (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

Is_rel_outside_PFA

Original_node_ID

Current_node_ID

A_ID

A_is_infected

A_gender

A_age

A_IP=’Risk’

A_total_num_active_rels

A_num_active_TRANSITORY_rels

A_num_active_INFORMAL_rels

A_num_active_MARITAL_rels

A_num_active_COMMERCIAL_rels

A_num_lifetime_rels

A_num_rels_last_6_mo

A_extra_relational_bitmask

A_is_circumcised

A_has_STI_coinfection

A_is_superspreader

B_ID

B_is_infected

B_gender

B_age

B_IP=’Risk’

B_total_num_active_rels

B_num_active_TRANSITORY_rels

B_num_active_INFORMAL_rels

B_num_active_MARITAL_rels

B_num_active_COMMERCIAL_rels

B_num_lifetime_rels

B_num_rels_last_6_mo

B_extra_relational_bitmask

B_is_circumcised

B_has_STI_coinfection

B_is_superspreader

A_CD4_count

B_CD4_count

A_viral_load

B_viral_load

A_HIV_disease_stage

B_HIV_disease_stage

A_HIV_Tested_Positive

B_HIV_Tested_Positive

A_HIV_Received_Results

B_HIV_Received_Results

883697

14235.2

14282.5

3

F

11

11

473090

0

0

19.6729

LOW

1

0

0

0

1

5

5

8

0

0

0

306143

1

1

33.0387

LOW

1

0

0

0

1

20

1

8

0

0

0

540.55

45.9653

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

883713

14235.2

14240.1

3

F

11

11

291007

1

0

34.0772

MEDIUM

2

0

0

0

2

13

2

8

0

0

0

247942

1

1

37.0004

LOW

3

0

0

0

3

19

3

8

0

0

0

239.501

58.8507

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883714

14235.2

14286.4

3

F

11

11

291007

1

0

34.0772

MEDIUM

3

0

0

0

3

14

3

8

0

0

0

306143

1

1

33.0387

LOW

4

0

0

0

4

23

4

8

0

0

0

239.501

45.9653

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883730

14235.2

14237.1

3

F

10

10

230518

1

0

38.2504

LOW

1

0

0

0

1

42

1

8

0

0

0

238647

1

1

37.6543

MEDIUM

1

0

0

0

1

36

1

8

0

0

0

237.113

50.3523

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883736

14235.2

14239.8

3

F

10

10

447988

1

0

21.6921

MEDIUM

3

0

0

0

3

8

3

8

0

0

0

457987

1

1

20.846

LOW

1

0

0

0

1

17

1

8

0

0

0

397.863

460.715

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883770

14235.2

14235.9

3

F

9

9

56366

1

0

39.6519

LOW

1

0

0

0

1

49

1

8

0

0

0

327868

1

1

31.4617

MEDIUM

2

0

0

0

2

27

2

8

0

0

0

37.3863

249.046

10000

10000

3

2

0

0

UNKNOWN

UNKNOWN

883785

14235.2

14256.4

3

F

9

9

268446

0

0

35.5965

MEDIUM

2

0

0

0

2

23

2

8

0

0

0

327868

1

1

31.4617

MEDIUM

7

0

0

0

7

32

7

8

0

0

0

540.55

249.046

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

883786

14235.2

14239.3

3

F

9

9

386619

1

0

26.9615

LOW

1

0

0

0

1

19

6

8

0

0

0

404054

1

1

25.4614

MEDIUM

4

0

0

0

4

17

4

8

0

0

0

436.587

100.519

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883807

14235.2

14236.1

3

F

8

8

258282

1

0

36.3081

LOW

1

0

0

0

1

60

1

8

0

0

0

269612

0

1

35.5196

LOW

1

0

0

0

1

36

1

8

0

0

0

245.487

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

883820

14235.2

14242.5

3

F

7

7

228857

1

0

38.3658

LOW

2

0

0

0

2

29

5

8

0

0

0

387565

1

1

26.9038

LOW

1

0

0

0

1

19

7

8

0

0

0

394.527

91.2097

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883823

14235.2

14246.8

3

F

7

7

361066

0

0

29

LOW

3

0

0

0

3

31

6

8

0

0

0

328341

1

1

31.4232

LOW

2

0

0

0

2

17

3

8

0

0

0

540.55

113.142

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

883824

14235.2

14237.7

3

F

7

7

450408

0

0

21.4998

MEDIUM

1

0

0

0

1

6

5

8

0

0

0

321950

0

1

31.904

MEDIUM

4

0

0

0

4

30

7

8

0

0

0

540.55

540.55

-1

-1

0

0

0

0

UNKNOWN

UNKNOWN

883854

14235.2

14246.3

3

F

6

6

457580

0

0

20.8844

LOW

3

0

0

0

3

5

4

8

0

0

0

505386

0

1

17.1153

LOW

7

0

0

0

7

9

9

8

0

0

0

540.55

540.55

-1

-1

0

0

0

0

UNKNOWN

UNKNOWN

883855

14235.2

14237.7

3

F

6

6

388797

1

0

26.7884

MEDIUM

1

0

0

0

1

15

2

8

0

0

0

503714

0

1

17.2499

MEDIUM

3

0

0

0

3

9

8

8

0

0

0

210.912

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

883856

14235.2

14242.4

3

F

6

6

388797

1

0

26.7884

MEDIUM

2

0

0

0

2

16

3

8

0

0

0

115436

1

1

39.6725

LOW

7

0

0

0

7

79

10

8

0

0

0

210.912

45.0356

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883880

14235.2

14236.9

3

F

5

5

479723

1

0

19.1152

LOW

5

0

0

0

5

8

7

8

0

0

0

128251

0

1

59.1656

LOW

4

0

0

0

4

57

11

8

0

0

0

496.747

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

883903

14235.2

14259

3

F

4

4

341794

1

0

30.4232

LOW

4

0

0

0

4

27

9

8

0

0

0

528563

0

1

15.5192

LOW

7

0

0

0

7

18

18

8

0

0

0

172.558

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

883912

14235.2

14239.1

3

F

4

4

234951

1

0

37.9235

LOW

4

0

0

0

4

31

6

8

0

0

0

523976

1

1

15.8269

MEDIUM

6

0

0

0

6

11

10

8

0

0

0

275.11

481.14

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883913

14235.2

14247.9

3

F

4

4

325272

1

0

31.6348

HIGH

1

0

0

0

1

637

14

8

0

0

0

523976

1

1

15.8269

MEDIUM

7

0

0

0

7

12

11

8

0

0

0

207.152

481.14

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883914

14235.2

14235.3

3

F

4

4

325272

1

0

31.6348

HIGH

2

0

0

0

2

638

15

8

0

0

0

215866

1

1

40.053

LOW

5

0

0

0

5

41

8

8

0

0

0

207.152

116.016

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883915

14235.2

14243.1

3

F

4

4

325272

1

0

31.6348

HIGH

3

0

0

0

3

639

16

8

0

0

0

363970

0

1

28.7885

LOW

8

0

0

0

8

35

13

8

0

0

0

207.152

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

883916

14235.2

14242

3

F

4

4

346843

1

0

30.0578

MEDIUM

3

0

0

0

3

35

6

8

0

0

0

459978

1

1

20.7114

LOW

5

0

0

0

5

10

7

8

0

0

0

228.651

358.639

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883925

14235.2

14237

3

F

3

3

464763

0

0

20.3267

MEDIUM

3

0

0

0

3

3

3

8

0

0

0

487005

1

1

18.5383

LOW

6

0

0

0

6

10

9

8

0

0

0

540.55

473.809

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

883949

14235.2

14248.4

3

F

2

2

377709

1

0

27.7115

LOW

5

0

0

0

5

24

7

8

0

0

0

290930

1

1

34.0964

LOW

3

0

0

0

3

26

7

8

0

0

0

76.2245

124.732

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883950

14235.2

14242.8

3

F

2

2

404758

0

0

25.4037

MEDIUM

1

0

0

0

1

22

3

8

0

0

0

356545

1

1

29.3462

LOW

4

0

0

0

4

40

6

8

0

0

0

540.55

98.4628

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

883967

14235.2

14968.7

0

F

1

1

423183

0

0

23.846

MEDIUM

2

2

0

0

0

19

2

9

0

0

0

410797

1

1

24.9037

MEDIUM

3

3

0

0

0

21

2

9

0

0

0

540.55

43.1436

-1

10000

0

3

0

0

UNKNOWN

UNKNOWN

883968

14235.2

14588.2

0

F

1

1

499985

1

0

17.4999

LOW

1

1

0

0

0

4

1

9

0

0

0

473508

1

1

19.6345

LOW

1

1

0

0

0

7

1

8

0

0

0

286.463

429.439

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

883969

14235.2

14691.2

0

F

1

1

398895

1

0

25.9038

MEDIUM

2

2

0

0

0

17

2

15

0

0

0

432555

1

1

23.0575

MEDIUM

2

2

0

0

0

14

1

15

0

0

0

90.2584

269.551

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

884026

14235.2

14359.3

0

F

1

1

366412

1

0

28.6154

HIGH

4

1

1

1

1

515

16

15

0

0

0

425812

1

1

23.6152

MEDIUM

3

3

0

0

0

19

2

9

0

0

0

177.698

47.4143

10000

10000

2

3

0

0

UNKNOWN

UNKNOWN

884027

14235.2

14378.2

0

F

1

1

375168

0

0

27.9423

LOW

1

1

0

0

0

11

2

9

0

0

0

424129

1

1

23.7691

MEDIUM

3

3

0

0

0

45

2

9

0

0

0

540.55

293.234

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN

884028

14235.2

14511.9

0

F

1

1

50041

1

0

45.0963

LOW

2

2

0

0

0

53

2

9

0

0

0

38447

0

1

51.9062

MEDIUM

1

1

0

0

0

14

1

8

0

0

0

53.1819

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

884038

14235.2

14290.7

1

F

1

1

328891

1

0

31.3848

LOW

1

0

1

0

0

8

1

8

0

0

0

326625

1

1

31.5386

MEDIUM

2

1

1

0

0

18

2

15

0

0

0

411.015

67.7839

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

884039

14235.2

14850.4

1

F

1

1

45201

1

0

58.6934

LOW

1

0

1

0

0

42

1

9

0

0

0

95691

0

1

58.8829

LOW

1

0

1

0

0

30

1

8

0

0

0

111.626

540.55

10000

-1

2

0

0

0

UNKNOWN

UNKNOWN

884040

14235.2

14239.3

3

F

1

1

408641

1

0

25.0768

HIGH

3

1

0

1

1

316

18

15

0

0

0

352684

1

1

29.6155

HIGH

2

1

0

0

1

593

24

15

0

0

0

329.253

209.064

10000

10000

2

2

0

0

UNKNOWN

UNKNOWN

884041

14235.2

14246.9

3

F

1

1

440926

1

0

22.3075

HIGH

3

1

0

1

1

305

21

15

0

0

0

496971

1

1

17.7499

HIGH

3

1

1

0

1

32

15

15

0

0

0

52.7971

51.8892

10000

10000

3

2

0

0

UNKNOWN

UNKNOWN

884042

14235.2

14236

3

F

1

1

511799

0

0

16.6538

HIGH

1

0

0

0

1

23

19

15

0

0

0

508411

1

1

16.8845

HIGH

4

0

1

1

2

75

27

15

0

0

0

540.55

47.8489

-1

10000

0

2

0

0

UNKNOWN

UNKNOWN
TransmissionReport

The HIV relationship transmission report (TransmissionReport.csv) provides detailed information about each transmission event and relationship members, evaluated at the time of disease transmission within the relationship. It includes the time/date of transmission and information about the transmitter and recipient, including: age, gender, current and lifetime number of relationships, infection stage, circumcision status for males, co-infections, and disease-specific biomarkers, if applicable.

Configuration

To generate the report, set the Report_Transmission parameter to 1 in the config.json file.

Output file data

The output report will contain the following information.

Note

Note: Data channels with <SRC or DEST> indicated will return one column for each partner: SRC (the source/transmitting partner) and DEST (the destination/receiving partner).

Data channel

Data type

Description

SIM_TIME

float

The time of simulation, in days, when the infection was transmitted.

YEAR

float

The time of the simulation, in units of calendar year, when the infection was transmitted. For STI simulations, this is the simulation time divided by 365. For HIV simulations, this is the simulation time divided by 365, added to the Base_Year value. If no base year is specified in the config.json file, the default value 2015 will be used.

NODE_ID

integer

The identification number of the node where the transmission event occurred.

REL_ID

integer

The unique ID of the relationship in which the transmission event occurred. This ID can be used between reports such as RelationshipStart.csv, RelationshipEnd.csv, and RelationshipConsummated.csv to cross-reference specific relationships.

REL_TYPE (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

integer

The type of relationship the participants were in at the time of the transmission event. Values for 0-3 as indicated in the header.

Is_rel_outside_PFA

boolean

Indicates whether or not the relationship was created by the normal process using the Pair Forming Algorithm (PFA), where 0 indicates the relationship was created using the PFA, and 1 indicates the relationship was created using the StartNewRelationship intervention.

<SRC or DEST>_ID

integer

The unique identification number of the individual. There is a column for each partner.

<SRC or DEST>_INFECTED

boolean

Describes whether or not the individual is infected: 0 for not infected, 1 for infected. There is a column for each partner.

<SRC or DEST>_GENDER

boolean

Describes the gender of the individual: 0 for male, 1 for female. There is a column for each partner.

<SRC or DEST>_AGE

float

The age of the individual in days, including fractions of days up to two decimal places. There is a column for each partner.

<SRC or DEST>_IP

string

A string of Key:Value pairs indicating the individual properties (IPs) that the individual has. The IP key and value are separated by a colon and the different Key:Value pairs are separated by commas (key1:value1,key2:value2,key3:value3). There is a column for each partner.

<SRC or DEST>_current_relationship_count

integer

The total number of relationships (of all types) that the individual was in at the time of the transmission event. There is a column for each partner.

<SRC or DEST>_lifetime_relationship_count

integer

The cumulative number of relationships (of all types) that the individual has been in prior to the transmission event. There is a column for each partner.

<SRC or DEST>_relationships_in_last_6_months

integer

The number of relationships (of all types) that the individual has had in the 6 months prior to the transmission event. There is a column for each partner.

<SRC or DEST>_FLAGS

integer

Indicates which types of relationships the individual is allowed to have when they have more than one active relationship. These values are configured using the Concurrency_Configuration parameter in the demographics file—see Demographics parameters for more information. These values can be updated when an individual migrates or has a value change in an individual property. The values are encoded in a 3-digit bitmask. In order, the digits correspond to Commercial (C), Marital (M), Informal (I), and Transitory (T) relationships. The following table provides example combinations:

Relationships allowed

Binary

Decimal Value

None

0000

0

T

0001

1

I

0010

2

I, T

0011

3

M

0100

4

M, T

0101

5

M, I

0110

6

M, I, T

0111

7

C

1000

8

C, T

1001

9

C, I

1010

10

C, I, T

1011

11

C, M

1100

12

C, M, T

1101

13

C, M, I

1110

14

C, M, I, T

1111

15

There is a column for each partner.

<SRC or DEST>_CIRCUMCISED

boolean

Indicates whether or not the individual is circumcised (only applicable to males): 0 for not circumcised (and females), 1 for circumcised. There is a column for each partner.

<SRC or DEST>_STI

boolean

Indicates whether or not the individual has an STI co-infection at the time of the transmission event, as determined by the ModifyStiCoInfectionStatus intervention: 0 if they do not have an STI co-infection, 1 if they do have an STI co-infection. There is a column for each partner.

<SRC or DEST>_SUPERSPREADER

boolean

Indicates whether or not the individual is a superspreader, as determined by the Probability_Person_Is_Behavioral_Super_Spreader demographics parameter. 0 for not a superspreader, 1 for the individual is a superspreader. There is a column for each partner.

SRC_INF_AGE

integer

The age in days at which the transmitting individual acquired their infection. One column is returned, as this only applies to the transmitting individual.

<SRC or DEST>_CD4

float

The CD4 count of the individual at the time of the transmission event. There is a column for each partner.

<SRC or DEST>_VIRAL_LOAD

float

Not currently supported; 10000 indicates that the individual is infected. There is a column for each partner.

<SRC or DEST>_STAGE

enum

Indicates the stage of HIV infection for the individual. Possible values are:

  • 0 = Uninfected

  • 1 = Untreated acute HIV infection

  • 2 = Untreated latent HIV infection

  • 3 = Untreated late/AIDS stage

  • 4 = On ART

There is a column for each partner.
Example

The following is an example of a TransmissionReport.csv report:

SIM_TIME

YEAR

NODE_ID

REL_ID

REL_TYPE (0 = TRANSITORY; 1 = INFORMAL; 2 = MARITAL; 3 = COMMERCIAL)

Is_rel_outside_PFA

SRC_ID

SRC_INFECTED

SRC_GENDER

SRC_AGE

SRC_IP

SRC_current_relationship_count

SRC_lifetime_relationship_count

SRC_relationships_in_last_6_months

SRC_FLAGS

SRC_CIRCUMSIZED

SRC_STI

SRC_SUPERSPREADER

SRC_INF_AGE

DEST_ID

DEST_INFECTED

DEST_GENDER

DEST_AGE

DEST_IP

DEST_current_relationship_count

DEST_lifetime_relationship_count

DEST_relationships_in_last_6_months

DEST_FLAGS

DEST_CIRCUMSIZED

DEST_STI

DEST_SUPERSPREADER

SRC_CD4

SRC_VIRAL_LOAD

SRC_STAGE

DEST_CD4

DEST_VIRAL_LOAD

DEST_STAGE

10

1995.03

4

5

0

0

1666

1

0

6084.83

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

6075.83

689

1

1

6871.07

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

539.57

10000

1

540.55

10000

1

14

1995.04

4

1

0

0

1214

1

0

8652.2

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8639.2

81

1

1

6974.44

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

538.584

10000

1

540.55

10000

1

23

1995.06

1

18

0

0

1926

1

0

6166.21

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

6144.21

1012

1

1

6559.79

Accessibility:No,InterventionStatus:None

1

1

1

0

0

0

0

537.466

10000

1

540.55

10000

1

33

1995.09

1

21

1

0

114

1

1

6544.43

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

6511.43

2246

1

0

8440.3

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

537.42

10000

1

540.55

10000

1

34

1995.09

1

42

0

0

1165

1

1

9988.67

Accessibility:No,InterventionStatus:None

1

1

1

0

0

0

0

9954.67

2566

1

0

10399.5

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

534.143

10000

1

540.55

10000

1

39

1995.11

3

31

1

0

2302

1

0

12310.6

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

12272.6

1513

1

1

8002.77

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

533.074

10000

1

540.55

10000

1

41

1995.11

2

14

1

0

2491

1

1

8167.69

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8127.69

95

1

0

7581.55

Accessibility:No,InterventionStatus:None

1

1

1

0

0

0

0

531.401

10000

1

540.55

10000

1

42

1995.12

1

59

1

0

2056

1

1

10173.5

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

10132.5

2753

1

0

15375.7

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

533.84

10000

1

540.55

10000

1

45

1995.12

1

46

1

0

1494

1

0

8982.86

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8938.86

302

1

1

6282.51

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

534.479

10000

1

540.55

10000

1

47

1995.13

2

65

0

0

2371

1

1

16856.8

Accessibility:Yes,InterventionStatus:OnPreART

1

1

1

0

0

0

0

16810.8

2179

1

0

16083.9

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

512.452

10000

1

540.55

10000

1

54

1995.15

3

53

0

0

859

1

0

6204.73

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

6151.73

2700

1

1

5419.33

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

531.255

10000

1

540.55

10000

1

59

1995.16

2

70

1

0

1726

1

1

10363

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

10305

854

1

0

11283

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

533.704

10000

1

540.55

10000

1

62

1995.17

1

84

0

0

2370

1

1

7972.11

Accessibility:Yes,InterventionStatus:None

1

2

2

0

0

0

0

7911.11

2658

1

0

8971.56

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

523.914

10000

1

540.55

10000

1

66

1995.18

3

103

1

0

1668

1

0

8805.51

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8740.51

1148

1

1

8611.91

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

532.607

10000

1

540.55

10000

1

68

1995.19

1

95

0

0

1454

1

1

5796.64

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

1

1

0

0

0

0

5729.64

962

1

0

7268.26

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

528.249

10000

1

540.55

10000

1

71

1995.19

1

19

1

0

1030

1

1

14358

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

14288

294

1

0

14584.1

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

507.882

10000

1

540.55

10000

1

80

1995.22

1

117

1

0

1004

1

0

6305.72

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

1

1

0

0

0

0

6225.72

2622

1

1

7099.56

Accessibility:Yes,InterventionStatus:None

1

2

2

0

0

0

0

505.374

10000

1

540.55

10000

1

82

1995.22

1

106

0

0

1985

1

0

8694.63

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8612.63

2230

1

1

5786.74

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

502.601

10000

1

540.55

10000

1

86

1995.24

1

75

0

0

1406

1

0

9943.64

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

9857.64

2679

1

1

6563.83

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

518.956

10000

1

540.55

10000

1

171

1995.47

1

236

0

0

1948

1

0

7052.93

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

6881.93

1728

1

1

7209.47

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

527.496

10000

2

540.55

10000

1

269

1995.74

2

357

0

0

1919

1

1

5610.26

Accessibility:Yes,InterventionStatus:LinkingToPreART

1

1

1

0

0

0

0

5341.26

1472

1

0

11706.9

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

71.2037

10000

3

540.55

10000

1

275

1995.75

3

403

1

0

2672

1

1

10489.7

Accessibility:Yes,InterventionStatus:None

1

2

2

0

0

0

0

10214.7

155

1

0

12476.6

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

477.849

10000

2

540.55

10000

1

322

1995.88

3

450

1

0

365

1

1

12148.9

Accessibility:Yes,InterventionStatus:None

1

2

2

0

0

0

0

11827.9

1709

1

0

13154.9

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

398.184

10000

2

540.55

10000

1

345

1995.95

2

546

0

0

1668

1

0

9084.51

Accessibility:Yes,InterventionStatus:None

1

3

1

0

0

0

0

8740.51

1204

1

1

5155.52

Accessibility:No,InterventionStatus:None

1

4

3

0

0

0

0

499.179

10000

2

540.55

10000

1

351

1995.96

4

510

1

0

2150

1

1

14164.2

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

13814.2

266

1

0

16810.8

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

460.215

10000

2

540.55

10000

1

412

1996.13

4

559

0

0

311

1

0

8952.07

Accessibility:Yes,InterventionStatus:None

1

2

1

0

0

0

0

8540.07

1075

1

1

7002.79

Accessibility:Yes,InterventionStatus:None

1

2

1

0

0

0

0

472.737

10000

2

540.55

10000

1

431

1996.18

1

193

2

0

1510

1

0

13523.7

Accessibility:Yes,InterventionStatus:None

1

1

0

0

0

0

0

13093.7

2008

1

1

10379.9

Accessibility:Yes,InterventionStatus:None

1

1

0

0

0

0

0

468.954

10000

2

540.55

10000

1

465

1996.27

4

739

1

0

2013

1

0

9166.06

Accessibility:Yes,InterventionStatus:None

1

1

1

0

0

0

0

8702.06

2092

1

1

8904.8

Accessibility:Yes,InterventionStatus:TestingOnANC

1

3

3

0

0

0

0

467.558

10000

2

540.55

10000

1

553

1996.52

3

853

0

0

1769

1

0

6042.47

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

2

1

0

0

0

0

5490.47

1521

1

1

7181.98

Accessibility:Yes,InterventionStatus:TestingOnANC

1

4

2

0

0

0

0

475.697

10000

2

540.55

10000

1

628

1996.72

1

1039

0

0

371

1

0

8615.26

Accessibility:Yes,InterventionStatus:None

1

3

2

0

0

0

0

7987.26

503

1

1

6796.32

Accessibility:Yes,InterventionStatus:None

1

3

1

0

0

0

0

420.477

10000

2

540.55

10000

1

676

1996.85

1

1080

1

0

678

1

0

9475.79

Accessibility:Yes,InterventionStatus:None

1

5

1

0

0

0

0

8799.79

2635

1

1

8821.51

Accessibility:Yes,InterventionStatus:TestingOnANC

1

2

2

0

0

0

0

348.661

10000

2

540.55

10000

1

716

1996.96

4

1187

1

0

2734

1

0

9252.79

Accessibility:No,InterventionStatus:None

1

3

2

0

0

0

0

8536.79

1748

1

1

6508.02

Accessibility:Yes,InterventionStatus:TestingOnANC

1

4

1

0

0

0

0

222.379

10000

2

540.55

10000

1

716

1996.96

2

1181

1

0

1612

1

1

12881.5

Accessibility:No,InterventionStatus:None

1

1

1

0

0

0

0

12166.5

2401

1

0

18140.1

Accessibility:No,InterventionStatus:None

1

1

1

0

0

0

0

328.111

10000

2

540.55

10000

1

953

1997.61

4

1509

0

0

354

1

1

11546.6

Accessibility:Yes,InterventionStatus:None

1

2

1

0

0

0

0

10594.6

504

1

0

9330.5

Accessibility:Yes,InterventionStatus:None

1

4

1

0

0

0

0

332.762

10000

2

540.55

10000

1

997

1997.73

2

1586

1

0

1020

1

0

5829.93

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

2

2

0

0

0

0

4833.93

83

1

1

6061.64

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

4

2

0

0

0

0

349.118

10000

2

540.55

10000

1

1028

1997.82

1

1614

1

0

2219

1

1

10157.1

Accessibility:Yes,InterventionStatus:None

1

3

2

0

0

0

0

9129.05

2581

1

0

13223.1

Accessibility:Yes,InterventionStatus:None

1

3

1

0

0

0

0

314.708

10000

2

540.55

10000

1

1148

1998.15

4

1899

1

0

2558

1

0

9564.76

Accessibility:Yes,InterventionStatus:None

1

6

1

0

0

0

0

8417.76

1843

1

1

8141.88

Accessibility:No,InterventionStatus:None

1

5

2

0

0

0

0

418.09

10000

2

540.55

10000

1

1213

1998.32

1

2047

1

0

1852

1

0

5870.9

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

2

2

0

0

0

0

4658.9

2489

1

1

6051.27

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

4

2

0

0

0

0

275.448

10000

2

540.55

10000

1

1534

1999.2

4

2581

1

0

1865

1

0

9955.24

Accessibility:Yes,InterventionStatus:None

1

6

2

0

0

0

0

8421.24

1980

1

1

5499.36

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

4

1

0

0

0

0

284.05

10000

2

540.55

10000

1

1552

1999.25

1

2614

1

0

2300

1

0

11300.5

Accessibility:Yes,InterventionStatus:None

1

2

1

0

0

0

0

9749.53

2468

1

1

7260.18

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

11

2

0

0

0

0

298.901

10000

2

540.55

10000

1

1585

1999.34

1

2705

0

0

1568

1

0

12349.7

Accessibility:No,InterventionStatus:None

1

5

2

0

0

0

0

10764.7

1958

1

1

8953.66

Accessibility:Yes,InterventionStatus:TestingOnANC

1

9

1

0

0

0

0

50.1538

10000

3

540.55

10000

1

1839

2000.04

2

3094

0

0

570

1

0

8784.15

Accessibility:Yes,InterventionStatus:None

1

5

1

0

0

0

0

6946.15

873

1

1

6644.39

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

6

3

0

0

0

0

359.168

10000

2

540.55

10000

1

1987

2000.44

2

3451

1

0

1644

1

1

9271.99

Accessibility:Yes,InterventionStatus:OnPreART

1

11

1

0

0

0

0

7285.99

1857

1

0

14118.5

Accessibility:Yes,InterventionStatus:None

1

4

1

0

0

0

0

400.743

10000

2

540.55

10000

1

2006

2000.5

2

3266

0

0

1117

1

1

7668.74

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

7

2

0

0

0

0

5662.74

2373

1

0

7592.66

Accessibility:No,InterventionStatus:None

1

3

1

0

0

0

0

312.542

10000

2

540.55

10000

1

2146

2000.88

1

3739

0

0

1825

1

0

7562.44

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

3

1

0

0

0

0

5416.44

1483

1

1

5537.63

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

3

3

0

0

0

0

138.688

10000

2

540.55

10000

1

2300

2001.3

4

3965

1

0

1911

1

0

9001.9

Accessibility:Yes,InterventionStatus:None

1

9

2

0

0

0

0

6701.9

1125

1

1

5808.57

Accessibility:No,InterventionStatus:None

1

6

2

0

0

0

0

334.617

10000

2

540.55

10000

1

2328

2001.38

2

3976

1

0

402

1

1

7950.15

Accessibility:Yes,InterventionStatus:OnART

1

9

1

0

0

0

0

5623.15

2040

1

0

7798.46

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

6

1

0

0

0

0

223.32

10000

3

540.55

10000

1

2664

2002.3

4

4627

1

0

2437

1

1

5741.89

Accessibility:Yes,InterventionStatus:LinkingToART

1

2

2

0

0

0

0

3078.89

1584

1

0

8533.6

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

9

1

0

0

0

0

49.7817

10000

3

540.55

10000

1

2689

2002.37

2

2834

2

0

2178

1

1

14669.4

Accessibility:Yes,InterventionStatus:None

1

2

0

0

0

0

0

11981.4

2064

1

0

15652

Accessibility:Yes,InterventionStatus:None

1

3

0

0

0

0

0

100.034

10000

2

540.55

10000

1

2771

2002.59

3

4815

1

0

2461

1

0

8916.71

Accessibility:Yes,InterventionStatus:None

1

8

3

0

0

0

0

6145.71

492

1

1

5995.74

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

7

1

0

0

0

0

297.231

10000

2

540.55

10000

1

2879

2002.89

4

4995

0

0

662

1

1

9159.44

Accessibility:Yes,InterventionStatus:None

1

13

2

0

0

0

0

6281.44

895

1

0

9196.95

Accessibility:No,InterventionStatus:None

1

12

3

0

0

0

0

318.755

10000

2

540.55

10000

1

3622

2004.92

1

6356

1

0

1983

1

0

7588.7

Accessibility:No,InterventionStatus:None

1

4

1

0

0

0

0

3966.7

175

1

1

5833.08

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

3

3

0

0

0

0

103.894

10000

2

540.55

10000

1

3920

2005.74

2

6878

0

0

1480

1

0

6362.7

Accessibility:Yes,InterventionStatus:LinkingToART

1

6

2

0

0

0

0

2442.7

343

1

1

6312.22

Accessibility:Yes,InterventionStatus:HCTTestingLoop

1

2

2

0

0

0

0

33.4509

10000

3

540.55

10000

1

4073

2006.16

1

7154

0

0

2006

1

0

7529.83

Accessibility:No,InterventionStatus:None

1

2

1

0

0

0

0

3456.83

304

1

1

5963.26

Accessibility:No,InterventionStatus:None

1

4

2

0

0

0

0

42.9939

10000

3

540.55

10000

1

4693

2007.86

2

5725

2

0

2127

1

1

19333.5

Accessibility:Yes,InterventionStatus:None

1

3

0

0

0

0

0

14641.5

1022

1

0

19818.7

Accessibility:Yes,InterventionStatus:None

1

2

0

0

0

0

0

39.2377

10000

3

540.55

10000

1

4853

2008.3

1

8574

0

0

1983

1

0

8818.7

Accessibility:No,InterventionStatus:None

1

10

2

0

0

0

0

3966.7

536

1

1

5201.13

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

2

2

0

0

0

0

33.1639

10000

3

540.55

10000

1

5192

2009.22

3

9161

0

0

2158

1

0

12948.9

Accessibility:Yes,InterventionStatus:OnART

1

23

1

0

0

0

0

7756.85

1782

1

1

10743.7

Accessibility:No,InterventionStatus:None

1

22

2

0

0

0

0

302.875

10000

3

540.55

10000

1

5592

2010.32

2

9877

0

0

2201

1

0

7427.72

Accessibility:Yes,InterventionStatus:HCTUptakePostDebut

1

3

1

0

0

0

0

1835.72

2048

1

1

6407.49

Accessibility:Yes,InterventionStatus:HCTTestingLoop

1

4

2

0

0

0

0

117.437

10000

2

540.55

10000

1

6958

2014.06

1

12541

1

0

2619

1

0

9268.38

Accessibility:No,InterventionStatus:None

1

13

1

0

0

0

0

2311.38

317

1

1

8580.63

Accessibility:Yes,InterventionStatus:HCTTestingLoop

1

15

1

0

0

0

0

80.6734

10000

2

540.55

10000

1

Tutorials and simulation examples

While the workings of the model are explained in detail in Understanding the model, it is often more useful to learn through hands-on implementation. To illustrate many of the concepts and capabilities of EMOD, IDM provides tested files to run example simulations that model a variety of disease scenarios. The directory for each scenario contains the files needed to run a simulation and generate the output graphs. Click EMOD scenarios to download a zipped folder containing all required files. These scenarios are referenced throughout the documentation where relevant.

Because all disease-specific EMOD simulation types are based on the generic model, the Generic model scenarios are helpful in learning the basics of modeling with EMOD, even if you intend to use one of the disease-specific simulation types. Additionally, the transmission-level scenarios are very relevant to modeling the diseases that build upon them.

Note

Because the EMOD model is stochastic, graphs you produce from the scenarios may appear slightly different from those included in the documentation.

Included files

The compiled EMOD executable (Eradication.exe) is included. Unlike other executables, you do not double-click this file to run simulations. Instead, EMOD simulations are run by calling Eradication.exe from the command line. For these scenarios, you can simply double-click the runEMOD.cmd file in each scenario directory, which contains the commands that will run the simulation.

Of course, you can also run simulations directly from the command line or using COmputational Modeling Platform Service (COMPS) if you choose. Review Running a simulation for complete information on running simulations from the command line, or just open the runEMOD.cmd file in a text editor to see what commands it contains.

The Scenarios directory contains subdirectories that contain scenarios for different simulation types. The README files in each of the scenario subdirectories describe what aspect of the model the scenario illustrates. Each scenario subdirectory contains the configuration and campaign files needed to run an EMOD simulation. Also included are plotting batch files that contain commands to run Python scripts. You can simply double-click the batch files to run these scripts and produce graphs.

The Demographics_Files directory contains the demographics files for all scenarios. The demographics files used with each scenario are listed in Demographics_Filenames in the configuration file. This directory also contains a few climate files used with the malaria scenarios.

The Scripts directory contains the Python scripts used to plot the output of the EMOD simulations. These are the scripts pointed to by the plotting batch files.

Most input files use JSON (JavaScript Object Notation) format. If you are unfamiliar with this format, see EMOD parameter reference.

Prerequisites

We recommend running these scenarios on a Windows computer. You must install the HPC, MPI, and Python packages described in Install EMOD on Windows. You do not need to download another copy of Eradication.exe, although it won’t hurt if you do.

Although EMOD also supports CentOS, the scripts to run simulations will not work and the installation instructions differ. However, you can still run simulations from the command line. See the CentOS installation instructions at Install EMOD on Linux.

General EMOD information

The features of the model are described in greater detail elsewhere in the documentation, but this provides a brief overview of the features most relevant to using these tutorials.

Manipulating population size

It is often useful to re-use the same demographics files for running different simulations. Depending on the dynamics of the simulation, or the output reports that are desired, it may be important to change the size of the population. An alternative to modifying the demographics file is to use the configuration parameter, x_Base_Population. This parameter lets you adjust the population set by the demographics parameter, InitialPopulation.

Overlay files

An alternative to changing parameter values or adding parameters to base files is to create what is called an “overlay file.” These files contain parameter settings or additional parameters that will overwrite the settings configured in the base configuration and demographic files. When using an overlay for configuration parameters, include the files in the working directory. For demographic overlay files, all files to be used must be listed in the array for Demographics_Filenames. The order of these files is important: the base file must be listed first, and the overlay listed second. When there is more than one overlay file, the order of the overlays determines what information will be overridden; the last file in order will overlay all files preceding it. Overlay files can make it simple to swap out different parameter values without having to modify the base files, so you can experiment with different settings. Demographic overlays make it simple to increase the complexity of the population structure without having to create complex files.

Weibull distributions

Many of the HIV parameters use a Weibull distribution. To explore the impact that the scale and heterogeneity parameters have on the shape of the distribution, there is an Excel spreadsheet called “Weibull.xlsx” included in the HIV scenarios folder.

Creating campaigns

Much of the power and flexibility of EMOD comes from the customizable campaign interventions. For more information on creating campaigns, see Creating campaigns. Briefly, campaigns are created through the hierarchical organization of JSON objects (parameter groups).

campaign event

Campaign events determine when and where an intervention is distributed during a campaign. “When” can be the number of days after the beginning of the simulation or at a point during a particular calendar year. “Where” is the geographic node or nodes in which the event takes place.

event coordinator

Event coordinators are nested within the campaign event JSON object and determine who receives the intervention. “Who” is determined by filtering on age, gender, or on the individual properties configured in the demographics files, such as risk group or sociodemographic category. See Individual and node properties.

individual-level intervention

Individual-level interventions determine what will be distributed to individuals to reduce the spread of a disease. For example, distributing vaccines or drugs are individual-level interventions. In the schema, these are labeled as IndividualTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births (the individual’s own birth), GaveBirth, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

Individual-level interventions can be used as part of configuring a cascade of care along with the individual properties set in the demographics file. Use Disqualifying_Properties to disqualify individuals who would otherwise receive the intervention and New_Property_Value to assign a new value when the intervention is received. For example, you can assign a property value after receiving the first-line treatment for a disease and prevent anyone from receiving the second-line treatment unless they have that property value and are still symptomatic.

node-level intervention

Node-level interventions determine what will be distributed to each node to reduce the spread of a disease. For example, spraying larvicide in a village to kill mosquito larvae is a node-level malaria intervention. Sometimes this can be an intermediate intervention that schedules another intervention. Node-level disease outbreaks are also configured as “interventions”. In the schema, these are labeled as NodeTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

All campaign events and event coordinators can be found in Events and event coordinators; node-level interventions can be found in Node-level interventions; and individual-level interventions can be found in Individual-level interventions.

Output reports

When you run a simulation using the runEMOD.cmd file, an output directory will be created that contains the output reports from the model. Some of these will be in JSON format and others in CSV. The standard report is InsetChart.json, which includes many different channels including births, deaths, cumulative infections, new infections, and more. You can enable other built-in reports by setting the appropriate parameter to 1 in the configuration file.

The HIV model includes a variety of different output reports created as .csv files. To create particular reports, enable the parameter by setting the value to 1 for the desired report. Note that some reports, such as the ReportHIVInfection.csv, will report information about each individual at each time step; it is not recommended to enable these types of reports when populations are large, as output files will become very large and the simulation will run very slowly.

For a complete list of all available output reports, see Output settings.

Generic model scenarios

The EMOD generic model is explained in detail in Model overview. While the various components that comprise the model are explained with examples, it may be more useful to learn the model through hands-on implementation. The following sections will introduce sets of example files that illustrate how the generic model works on particular topics. All files are available in the downloadable EMOD scenarios > Scenarios > Generic folder and, in addition to the explanations below, each scenario will have a more detailed README file to cover relevant information.

EMOD supports different simulation types for various diseases and disease classes. The features present in the GENERIC_SIM simulation type, which can be configured to model a variety of different diseases, are inherited by the more specific simulation types, such as malaria or HIV. Because all disease-specific EMOD simulation types are based on the generic model, the following scenarios are helpful in learning the basics of modeling with EMOD, even if you intend to use one of the disease-specific simulation types.

For more information on the software architecture and inheritance, see Overview of EMOD software.

Compartmental models

Before working with an agent-based model like EMOD, you will likely be familiar with deterministic compartmental models. In these models, an ordinary differential equation (ODE) controls the rate at which the population transitions from each disease state (compartment) to another. These models assume that individuals within each compartment are identical and the entire population is well-mixed. Given the same inputs, a compartmental model will always produce the same outcomes.

While compartmental models are very useful, in many situations an agent-based model is a better tool for describing complex phenomena. In these models, each agent (such as a human or a vector) is simulated individually. Their behavior and interactions with one another are determined using decision rules. For a more detailed comparison of EMOD and compartmental models, see Compartmental models and EMOD.

The following scenarios under EMOD scenarios > Scenarios > Generic show how you can use EMOD to simulate disease scenarios that might also be simulated using a compartmental model. For example, a disease like measles could be modeled using a compartmental SIR model or it could be modeled using EMOD configured such that there is no incubation period or waning immunity after infection.

  • SI

  • SIS

  • SIR

  • SIRS

  • SEIR

  • SEIR_VitalDynamics

  • SEIRS

Density scaling of infection

By default, EMOD uses frequency-dependent transmission and the overall transmissibility does not change with population size or density. An infected individual will infect the same number of people either in a small village or in a metropolitan area. The EMOD scenarios > Scenarios > Generic >DensityScaling scenario shows how you can configure EMOD so population density has an effect on the transmissibility of disease. For a detailed description of the mathematics behind this functionality, see Population density and transmission scaling.

Heterogeneous transmission

By default, the probability of transmitting disease to another is the same within each node in an EMOD simulation. However, we know that some people may be at greater risk based on their behavior, environment, or biology. The Heterogeneous Intra-Node Transmission (HINT) feature enables you to specify values for heterogeneity in transmission based on individual properties in a WAIFW matrix. For detailed information, see Property-based heterogeneous disease transmission (HINT).

EMOD scenarios > Scenarios > Generic > HINT_AgeAndAccess illustrates a common scenario in which the population has properties applied based on age and accessibility. Transmission is higher among individuals of similar ages and accessibility levels. Interventions are targeted based on these properties.

EMOD scenarios > Scenarios > Generic > HINT_SeattleCommuting illustrates a more novel scenario that uses the HINT feature. To simulate migration in EMOD, you can run multi-node simulations where individuals have a certain probability of migrating to a different node at each timestep (typically set to one day). This works well when individuals move to another location permanently or seasonally. However, for daily movement like commuting for work, you can use HINT to make transmission higher for people in the same area during the workday. This scenario assigns individual properties that represent the area codes surrounding Seattle and configures higher transmission for people in the same area code.

Disease reservoirs

Generally with EMOD, you model a disease by introducing an outbreak at some point in the simulation. However, endemic settings may involve a non-human disease reservoir that periodically reintroduces the disease to the human population. The EMOD scenarios > Scenarios > Generic > Zoonosis scenario illustrates how to configure EMOD to simulate such zoonotic diseases. For detailed information, see Disease outbreaks, reservoirs, and endemicity.

Interventions

The EMOD scenarios > Scenarios > Generic > Vaccinations scenario introduces the concept of adding interventions to stop disease transmission. It compares the outcomes when a disease outbreak has no interventions applied, when the entire population is vaccinated, and when you target the vaccination to a particular segment of the population.

Because interventions are often very specific to the disease being modeled, the other simulation types introduce diagnostic tests, drugs, and health system elements relevant to that disease. Therefore, the scenarios for the disease-specific simulation types provide more examples of intervention configuration. For detailed information, see Creating campaigns.

STI model scenarios

The EMOD STI model is explained in detail in STI model overview. While the various components that comprise the model are explained with examples, it may be more useful to learn the model through hands-on implementation. The following sections will introduce sets of example files that illustrate how the STI model works on particular topics. All files are available in a downloadable EMOD scenarios zip file and, in addition to the explanations below, each scenario will have a more detailed README file to cover relevant information.

For more information on the software architecture and inheritance, see Overview of EMOD software.

Relationship networks

To use a contact network as the basis for disease transmission, the Simulation_Type should be set to STI_SIM.

In the EMOD scenarios > Scenarios > STI > Relationship_networks folder, you will find sets of files to run simulations modeling contact networks. These simulations do not include disease outbreaks or subsequent transmission, but will demonstrate how to configure relationship networks beginning with eligibility for pair formation, preference for particular partner ages, relationship types and durations, concurrency in relationships, and coital frequency and dilution.

HIV model scenarios

The EMOD HIV model is explained in detail in HIV model overview. While the various components that comprise the model are explained with examples, it may be more useful to learn the model through hands-on implementation. The following sections will introduce sets of example files that illustrate how the HIV model works on particular topics. All files are available in a downloadable EMOD scenarios zip file and, in addition to the explanations below, each scenario will have a more detailed README file to cover relevant information. Within the EMODScenarios > Scenarios > HIV folder is an Excel worksheet titled “Weibull.xlsx,” which can be used to explore how Weibull parameters influence the shape of the distribution. Note that Weibull parameters are used often in the HIV model, so it will be useful to to understand the factors governing their shape.

For more information on the software architecture and inheritance, see Overview of EMOD software.

HIV-specific biology

HIV parameters are added to the STI relationship networks when the Simulation_Type is set to HIV_SIM. Specifically, this adds transmission rates, mortality rates, and the evolution of biomarkers such as CD4 count specific to HIV-infected individuals. These factors impact the survival of HIV+ individuals according to their age, disease state, co-infection status, and use of antiretroviral therapy (ART) or other interventions.

In the EMOD scenarios > Scenarios > HIV > HIVBiology folder you will find files to run an HIV simulation. In the README file, you will find instructions on how to configure baseline HIV transmission, how to change survival time for children and adults, how CD4 count and WHO stage progress, and how to configure heterogeneity in CD4 count.

Transmission

HIV can be transmitted via two routes: sexually through a relationship network, or vertically by mother-to-child transmission. In EMOD, to initially seed a population with disease, you must use the campaign interventions Outbreak or OutbreakIndividual (see Outbreak or OutbreakIndividual for more information). These two campaign intervention classes work by “distributing” HIV to the configured population. After the initial seeding, transmission can occur via the sexual or vertical routes.

In the EMOD scenarios > Scenarios > HIV > Transmission folder you will find files to run an HIV simulation. In the README file, you will find instructions on how to configure sexual transmission, vertical transmission, and how to initiate co-infections.

For detailed configuration instructions and example exercises to try, see the README in the Transmission folder.

Health care

Health care is critical for individuals with HIV. In EMOD, a system of health care can be created by using multiple interventions. Interventions can be linked to create a network of actions and results, where the outcome of one intervention can initiate the start of the next. This creates a cascade of care, where individuals enter the system due to a positive diagnostic test, and then move through the healthcare system created, with options for follow-up tests, and treatment options. Some individuals will exit the care system (e.g. “lost to follow up”), and in some cases, individuals that exit the care system may re-initiate care and return.

In the EMOD scenarios > Scenarios > HIV > Health_care folder, you will find files to run simulations with a configured cascade of care. In the README file, you will be provided with instructions for working with cascades of care.

Care systems can range from simple diagnostics to a series of complex interventions, and the files within this section highlight these important aspects. Several interventions involved with care are highlighted, namely:

  • Voluntary male medical circumcision (VMMC)

  • Prevention of mother-to-child transmission (PMTCT)

  • Antiretroviral treatment (ART)

  • Steps in the care process, such as testing, staging, linking to care, treatment eligibility, and how to prevent individuals from entering care cascades multiple times.

Troubleshooting EMOD simulations

If you encounter any of the following problems when attempting to run EMOD simulations, see the information below to resolve the issue.

If you need assistance, you can contact support for help with solving issues. You can contact Institute for Disease Modeling (IDM) support at support@idmod.org. When submitting the issue, please include any error information. See Debugging and testing for troubleshooting issues when attempting to build Eradication.exe or Eradication binary for Linux.

Exceptions

Whenever EMOD encounters an error condition while running a simulation, it should throw an exception. These exceptions are designed to help you diagnose any problems so that you can quickly resolve the issue. You can find the exceptions code in the utils directory of the EMOD source code within the files Exceptions.h and Exceptions.cpp.

Each exception will return, at a minimum, the following information:

  • Exception type caught

  • The filename where the exception occurred

  • The line number in the file where the exception was thrown (which may not be exactly where the error actually occurred in the code)

  • The function name where the exception was thrown

Specific exceptions may also return additional information in a message format. This message (msg) may contain variable names or the values of those variables, the name of a file that wasn’t found, and other informational text regarding the nature of the problem. For example, a file not found exception (FileNotFoundException) might look similar to the following:

00:00:00 [0] [E] [Eradication] FileNotFoundException caught: msg = Could not find
file ./Namawala_single_node_demographics.compiled.json, filename = NodeDemographics.cpp,
lineNumber = 227
BadEnumInSwitchStatementException

This exception is thrown when an enumeration value is not handled in the switch statement. In other words, this exception signals that there is a problem with an enumeration value, typically stemming from one of the configuration files, though this is not always the case.

It is possible the enumeration value is not a valid value (out of range of the numeric range of the enumeration), or perhaps the string value is currently not implemented in the code (and should not be used in configuration settings yet).

BadMapKeyException

This exception is thrown when there is a standard template library (STL) mapping error. Usually, this occurs where spatial output channel names are specified in the configuration file if an unrecognized channel name is used.

If you have not modified the EMOD source code or used an unrecognized channel name, this error could signal an internal problem with the code. Contact support@idmod.org.

CalculatedValueOutOfRangeException

EMOD performs a large number of mathematical operations on parameter values. Therefore, it is possible that, despite original parameter values being with range, the values resulting from these multiple calculations may end up outside its valid range. For example, a probability value (range: 0 to 1.0) that after multiple calculations during a simulation now exceeds 1.0.

This exception is thrown when such a situation is detected. This exception only applies to numeric or Boolean values, not enumeration values.

ConfigurationRangeException

This exception is thrown if a parameter value read from a configuration file is detected to be outside its valid range. This exception is similar to the more general case OutOfRangeException. However, this exception is only thrown if the out of range exception comes from a numeric or Boolean value, not enumeration value, read from a configuration file.

DllLoadingException

The EMOD architecture is modularized and can be built as a core Eradication.exe along with a series of custom reporter EMODules, as opposed to a single monolithic Eradication.exe. This exception indicates that EMOD couldn’t load on of the EMODule DLLs.

This situation could occur for several reasons:

  • EMOD couldn’t find the EMODule

  • Unresolved symbols were found (Windows)

  • EMOD could not find the necessary symbol during the GetProcAddress call

  • The custom reporter EMODules were built using a version of Visual Studio that is no longer supported. Rebuild the EMODules using Visual Studio 2022 (Professional, Premium, or Ultimate).

FactoryCreateFromJsonException

EMOD implements class factories that instantiate objects at run time and use information from JSON- based configuration information in the creation of these objects. The exception indicates something is incorrect with the JSON information.

In particular, in some cases, the JSON information is nested into a hierarchy of information. Therefore, as the factories are called to create the objects described by the outer layers of one of these nested hierarchies, the factories do not have any knowledge yet of the inner layers of the hierarchies. This inner information contains information the factory needs to complete the object instantiation, but this information might not be correct. If that happens, then the factory will throw this exception.

Campaign files often have this kind of nested hierarchical structure, so it’s important to t verify that the hierarchy is set up correctly. For example, if the class name were mistyped and EMOD had no implementation of that class, this exception will be thrown.

FileIOException

This exception is generated if there is an unrecoverable problem loading data from a file. The data might be corrupted or there may be a mismatch. For example, if the file format or configuration information indicates that there should be ten values of some array and there are only nine included in the file, then this exception would be thrown.

This exception is not the same as the exception thrown for a file that is not found. In this case, the file is found and loaded, but there is a problem with the data in the file.

FileNotFoundException

This exception is thrown if a file cannot be found. Possible causes might include a incorrectly typed filename in the configuration file, a wrong path to the file, or even the path not being set in the system environment leading to the system not finding a relative path to the file. One of the most likely causes is that quotes are missing around the file name.

GeneralConfigurationException

This exception is only thrown if a more specific exception cannot be used for the configuration problem detected. This exception is likely thrown when there is very little information available about the root problem.

For example, this exception might be thrown if a parameter name is invalid, such as using an older, deprecated version of a parameter name.

In STI and HIV simulation types, this may occur when referring to CD4MeasuredX and AgeMeasuredX in the ReportEventRecorder settings. These are built-in triggers that must be explicitly defined in the Custom_Individual_Events array of the configuration file. For example:

{
    "Listed_Events": [
        "CD4Measured0",
        "CD4Measured1",
        "CD4Measured2"
    ]
}
IllegalOperationException

This exception is thrown if an illegal operation was detected. In most cases, a more specific exception will be thrown rather than this more general one. This exception is likely thrown when there is very little information available about the root problem. For example, when a utility function error is detected, there is very sparse information available as to what may have led to the error. As a result, calling a more specific exception with more context is not an option.

IncoherentConfigurationException

This exception is thrown if mutually contradictory or incompatible configuration settings have been detected. For example, if mutually exclusive parameters are set, the minimum parameter value is greater than the maximum value, or two distribution axes are specified in a demographics file but there is a mismatch with the number of axes scale factors included. The exception can also occur if there isn’t a corresponding mapping between an reference ID in the metadata of a demographics file and its corresponding data file.

InitializationException

This exception is thrown if a problem with initialization was detected. In most cases, a more specific exception will be thrown rather than this more general one. This exception is likely thrown when there is very little information available about the root problem.

For example, if the very first part of a JSON file has corrupted or badly formatted data, this exception may be thrown instead of the more expected file input/output exception, FileIOException.

InvalidInputDataException

This exception is thrown when a problem with an input file is detected. For example, if the wrong data type was detected, such as a float being detected when a string is expected you would see this exception thrown, or even, if a parameter has an invalid value even if the value is of the correct type. As the input file most likely to have significant modifications, verify that the demographics file is set up correctly.

MissingParameterFromConfigurationException

This exception occurs when required parameters are missing. Verify that you are not using deprecated parameters and that all required parameters are specified (or set Use_Defaults to 1).

MPIException

This exception is thrown if there is an MPI error. As such, these types of issues are related to interfacing with MPI (and/or networking issues) and do not necessary imply something wrong with the EMOD code or JSON files.

NotYetImplementedException

This exception is thrown if an attempt is made to execute code that is not yet implemented. For example, there are areas of EMOD where placeholder enumeration values are defined but not yet implemented. If you specify a value like this, it is considered within a valid range, but this exception will be thrown in response. Verify that any enumeration values use one of the available values as described in the documentation and do not contain any typos.

NullPointerException

This exception is thrown when a NULL pointer is detected in the code, or rather when a NULL pointer - that should NOT be NULL - is used. When thrown at the application level, a NULL pointer exception is usually caused by some sort of initialization error, for example, a file not being found.

As a result, in most cases, a more specific exception will be thrown before the code execution reaches a point where this exception would occur. Therefore, this exception is uncommon and likely thrown only when there is very little information available about the root problem.

OutOfRangeException

This exception is thrown when a numeric or Boolean value is out of range. For example, if you index an array outside of its valid range, this exception will be thrown. There are other situations where more specific exceptions are thrown instead of this more general one. For example, when the numeric or Boolean values are from a configuration file, but are detected to be out of range, the ConfigurationRangeException is thrown. Likewise, if the value goes out of range as the result of a calculation, the CalculatedValueOutOfRangeException is thrown instead.

QueryInterfaceException

The EMOD architecture is modularized and many components now implement QueryInterface. This exception is thrown when a required interface is queried on an object and the object that returns that the interface is not supported.

If you have not modified the EMOD source code and receive this error, it could signal an internal problem with the code. Contact support@idmod.org.

SerializationException

This exception is thrown when there is a serialization (or de-serialization) issue. For example, if data is being passed over the network (MPI) and the connection drops, then the serialization fails and this exception is thrown.

CentOS environment

The following problems are specific to running simulations using the Eradication binary for Linux on CentOS 7.1.

Regression test graphs differ when run on CentOS

After you run regression simulations on CentOS using runemod.sh in the Scripts directory, it plots graphs from the simulation output data with a red line for the reference output and a blue line for the new output. The reference output was created by running the simulation on Windows, which in some cases may be slightly different than the output from CentOS.

For simulations that plot a baseline, you can override the Windows reference output by modifying runemod.sh to use output/InsetChart.linux.json as the output location. In that case, the red reference plots should always be completely covered by the blue plots.

Eradication binary for Linux cannot locate the input files

If you chose not to have the PrepareLinuxEnvironment.sh script download the EMOD source code and input files, you need to set up the environment variable, path and symlink that are needed to run simulations on CentOS. See Install EMOD on Linux.

Model overview

Disease models play an important role in understanding and managing the transmission dynamics of various pathogens. We can use them to describe the spatial and temporal patterns of disease prevalence, as well as to explore or better understand the factors that influence infection incidence. Modeling is a key step in understanding what treatments and interventions can be most effective, how cost-effective these approaches may be, and what specific factors need to be considered when trying to eradicate disease. The findings can be used to guide policy for implementing practical real-world solutions.

To understand the complex dynamics underlying disease transmission, epidemiologists often use a set of models called compartmental models. Developed in the early 20th century, these models stratify a population into groups, generally based on their risk or infection status. Underlying these models is a system of differential equations that track the number of people in each category over time. If you would like a more in-depth introduction to epidemiology and disease modeling, you may want to take the Epidemics course from The Pennsylvania State University through Coursera.

Epidemiological MODeling software (EMOD) is an agent-based model (ABM), another powerful tool used to help understand the complexity inherent in disease transmission systems. EMOD is a discrete time, Monte Carlo method simulator that simulates the simultaneous interactions of agents in an effort to recreate complex phenomena. Each agent (such as a human or vector) can be assigned a variety of properties (for example, age, gender, etc.), and their behavior and interactions with one another are determined using decision rules. EMOD and other ABMs must be run many times to produce probability distributions of potential outcomes, better capturing uncertainty than compartmental models.

These models have strong predictive power and are able to leverage spatial and temporal dynamics. Further, complex environments can be developed in which the agents act, and agents may “learn” from interactions or “adapt” to their environment. As a result, ABMs are excellent for identifying emerging properties of the system: patterns that are not explicitly modeled, but instead occur as a consequence of the rules that govern the agents.

EMOD can be calibrated to particular geographic locations, and the microsolver framework enables the model’s functionality to be highly modifiable. Further, the framework includes the ability to add intervention campaigns, and those interventions can be specified to target particular populations or sub-populations of human or vector groups. This intervention targeting is capable of simulating complex cascade of care systems, such as those used in the treatment of HIV. EMOD is very useful for determining the best intervention strategies to use in particular areas for burden reduction or elimination.

EMOD supports different simulation types for various diseases and transmission types. EMOD uses a layered architecture in which the base functionality is contained in the generic model and inherited by the transmission-level models that in turn are inherited by specific disease models. Because the EMOD modeling software can simulate all of these diseases, each “model” is more accurately referred to as a simulation type. For more information on the software architecture and inheritance, see Overview of EMOD software.

_images/simulation-types.png

Simulation type inheritance

The generic model can be configured to simulate a variety of different diseases, such as measles or influenza. Support for other transmission mechanisms, such as sexual networks or vector transmission, is provided by the transmission-level models. These can be configured to model diseases we do not specifically support. For example, IDM collaborators have used the vector model to simulation the transmission of dengue and chikungunya. Finally, there are models for specific diseases that include logic for disease biology and treatment. Because of this inheritance, we recommend reviewing the documentation for the generic model and the transmission-level model relevant to your disease simulation. The fundamentals for configuring outbreaks, heterogeneity, and interventions are the same across all simulation types.

Generic model overview

The EMOD generic model forms the foundation for all other disease models in EMOD. It provides the fundamental logic for contact-based disease transmission and interventions aimed at controlling the spread of disease that are targeted to individuals or geographic nodes. You can easily add heterogeneity to your simulation by configuring he infectivity of the disease, susceptibility of individuals, and more. The generic model does not contain logic for disease biology, but it can be configured to model a variety of diseases, such as influenza, Ebola, measles, and more. To use the generic model, set the configuration parameter Simulation_Type to GENERIC_SIM.

The figure below demonstrates the main components of the generic EMOD simulation type. Individuals reside in geographic nodes and can migrate from one node to another. Infected individuals shed contagion into a pool that can infect susceptible individuals. You can assign properties to individuals and nodes to vary how transmission or interventions occur.

_images/GenericModel_Flowchart.png

In the generic model, you can add heterogeneous transmission in a population using the Heterogeneous Intra-Node Transmission (HINT) feature. Using this feature, you assign different properties to individuals in a population and differentially scale the infectivity from one group to another. For example, you might have high infectivity between schoolchildren and lower infectivity from the elderly to children. For more information, see Property-based heterogeneous disease transmission (HINT). This feature is not available in most other disease models, where heterogeneity in transmission is handled more mechanistically. For example, the malaria model simulates parasite density, mosquito populations, and biting frequency.

If you are familiar with compartmental models but new to agent-based models, we recommend reviewing the Compartmental models and EMOD section, which compares the mathematics of the differential equations that govern compartmental models with the mathematics of the EMOD agent-based model. It describes how to configure EMOD to model diseases like SI, SIR, or SEIR models. Additionally, review Tutorials and simulation examples for hands-on experience running EMOD simulations.

The configuration of the model regarding infectivity, immune response, and other qualities is handled via several JSON (JavaScript Object Notation) files. For more information, see Overview of EMOD software.

Compartmental models and EMOD

This section describes the common compartmental models, the ordinary differential equations governing them, and how to configure EMOD to model similar disease scenarios. The simplest way to model epidemic spread in populations is to classify people into different population groups or compartments. Compartmental models are governed by a system of differential equations that track the population as a function of time, stratifying it into a different groups based on risk or infection status. The models track the number of people in each of the following categories:

Susceptible

Individual is able to become infected.

Exposed

Individual has been infected with a pathogen, but due to the pathogen’s incubation period, is not yet infectious.

Infectious

Individual is infected with a pathogen and is capable of transmitting the pathogen to others.

Recovered

Individual is either no longer infectious or “removed” from the population.

Different diseases are represented by different compartmental models. For example, a disease without an incubation period is represented by an SIR model and a disease that has lifelong infectiousness is represented by an SI model. Each of these models are discussed in more detail in the topics in this section.

Compartmental models are deterministic, that is, given the same inputs, they produce the same results every time. They are able to predict the various properties of pathogen spread, can estimate the duration of epidemics, and can be used to understand how different situations or interventions can impact the outcome of pathogen spread.

Agent-based models like EMOD model individual agents (such as humans or vectors) and are extensively used in epidemiology due to their predictive power in modeling the spread (or conversely, control) of epidemics. A popular type of ABM for this is one in which each agent’s rules follow the dynamics specified in the compartmental models, where each agent flows through the compartments as a function of both “within-host” rules (such as duration of infection) and interactions between agents (such as becoming infected when coming into contact with an infectious agent).

By combining the epidemiological basis of compartmental models with the flexibility of an agent- based model, this type of ABM is quite powerful due to their ability to simultaneously address the ecology, epidemiology, and pathology of complex systems. In addition, EMOD is a stochastic model that better captures the randomness involved in real-world disease transmission. Therefore, you must run multiple simulations and and then run statistical analyses of the output to achieve valid predictions.

Detailed model comparison

Because the SIR model is the most commonly-used compartmental model from which many others are derived, it is used for the detailed comparison between compartmental models and the EMOD agent- based model. However, the principles can be extended to all compartmental models discussed in this section.

Compartmental models

The SIR/SIRS diagram below shows how individuals move through each compartment in the model. The dashed line shows how the SIR model becomes an SIRS (Susceptible - Infectious - Recovered - Susceptible) model, where recovery does not confer lifelong immunity, and individuals may become susceptible again.

_images/SIR-SIRS.png

SIR - SIRS model

The infectious rate β controls the rate of spread, which represents the probability of transmitting disease between a susceptible and an infectious individual. Recovery rate, γ = 1/D, is determined by the average duration, D, of infection. Including births and deaths (where the rates are equal), the SIR model can be written as the following ordinary differential equation (ODE):

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = \mu N -\frac{\beta S I}{N} - \nu S\\ \frac{dI}{dt} & = \frac{\beta S I}{N} - \gamma I - \nu I\\ \frac{dR}{dt} & = \gamma I - \nu R \end{aligned}\end{split}\]

with \(N = S + I + R\) and \(\mu\) is the birth rate and \(\nu\) is the death rate.

It is challenging to derive exact analytical solutions of the previous equations because of the non- linear dynamics. However, the key metrics that control the spread can be derived. At the initial seeding of the infection, the following condition needs to be satisfied for a disease to spread:

\[\frac{dI}{dt} = \frac{\beta SI}{N} - \gamma I > 0\]

If the number of infections at the initial stage is small then S is close to N and the condition becomes:

\[\frac{\beta}{\gamma} > 1\]

where \(\frac{\beta}{\gamma}\) is named the reproductive number (R0). R0 is the average number of secondary cases generated by an index case in a fully susceptible population. The disease will spread in the population when R0 > 1 and will die out if R0 < 1. This is true for all compartmental models.

EMOD model

The EMOD model is a discrete and stochastic version of the SIR model with state changes occurring at fixed time steps and an exponentially distributed duration of infection. Because transmission is an inherently stochastic process that unfolds in a population of finite size, this is preferable though you cannot precisely replicate the deterministic and continuous dynamics of an ODE model. Because EMOD represents individuals, and to be clear about mechanisms by which the transmission rate varies as a function of the node population, we instead present the dynamics in terms of the number of individuals (X, Y ,Z) in place of (S, I, R), respectively. The discrete form of the previous equation at each time step can be written as:

\[\begin{split}\begin{aligned} X(t+\delta) & = X(t) \mu N - \delta\frac{\beta X(t)Y(t)}{N} - \nu X(t)\\ Y(t+\delta) & = Y(t) + \delta\frac{\beta X(t)Y(t)}{N} - \delta\gamma Y(t) - \nu Y(t)\\ Z(t+\delta) & = Z(t) +\delta\gamma Y(t) - \nu Z(t) \end{aligned}\end{split}\]

In EMOD, the state changes at fixed time steps. The size of the time step, denoted \(\delta\), is selected to be small compared to the characteristic timescale of the disease dynamics. By default, \(\delta\) = 1, which is one day but you can choose a smaller time step in order to get more accurate results. The infection and recovery process can be represented as probabilistic binomial draws where each update step consists of three primary sub-steps:

  1. Shed: The default behavior in a homogeneous generic simulation is for each infected individual to shed contagion at a fixed rate. The total rate of contagion shedding from all infected individuals is called the force of infection, \(\lambda = \frac{\beta I}{N}\).

  2. Expose: Each susceptible individual becomes infected with probability \(p_i = 1-\mathrm{e}^{\lambda\delta}\), where \(\delta\) is the time step.

  3. Finalize: The final part of each time step contains recovery from infection and disease mortality for infected individuals, along with basic demographic updates. EMOD supports advanced demographics, but here we use the per-capita birth and death rates.

    1. Recovery: Each infected individual recovers in one time step with probability, \(p_r = 1 - \text{exp}(-\gamma\delta)\).

    2. Birth: For birthrate \(\mu\), the number of new susceptible individuals will be Poisson distributed with rate \(p_b = \mu N\delta\).

    3. Natural Death: The probability of death for each individual is \(p_d = 1 - \text{exp}(-\nu\delta)\).

Putting these pieces together over the course of a time step, let:

\[\begin{split}\Delta{N_i} & \sim \text{Binomial}(X,p_i) \qquad [\text{Infection}] \\ \Delta{N_r} & \sim \text{Binomial}(Y,p_r) \qquad [\text{Recovery}] \\ \Delta{N_b} & \sim \text{Binomial}(\mu N\delta) \qquad [\text{Birth}] \\ \Delta{N_{X,d}} & \sim \text{Binomial}(X,p_d) \qquad [\text{Death of susceptibles}] \\ \Delta{N_{Y,d}} & \sim \text{Binomial}(Y,p_d) \qquad [\text{Death of infected}] \\ \Delta{N_{Z,d}} & \sim \text{Binomial}(Z,p_d) \qquad [\text{Death of recovered}]\end{split}\]

With these numbers in mind and assuming that only one state transition event happens to each individual in a time step:

\[\begin{split}\begin{aligned} X(t + \delta) &= X(t) - \Delta{N_i} + \Delta{N_b} - \Delta{N_{X,d}} \\ Y(t + \delta) &= Y(t) + \Delta{N_i} - \Delta{N_r} - \Delta{N_{Y,d}} \\ Z(t + \delta) &= Z(t) + \Delta{N_r} - \Delta{N_{Z,d}} \\ t &= t + \delta \end{aligned}\end{split}\]

One of the key differences between stochastic and deterministic systems is the value of R0. An ODE model will never predict an outbreak when R0 < 1, especially when R0 is close to 1. In stochastic simulations it is possible to see outbreaks.

Additionally, the EMOD model is individual-based, which allows the implementation of flexible distributions. In an ODE model the time constants are exponentially distributed, however, this is not the case for some diseases. You can test the effects of different distributions in the EMOD executable by changing Infectious_Period_Distribution in the configuration file. A fixed duration will result in a much faster spread of disease.

SIR and SIRS models

This topic describes the differential equations that govern the classic deterministic SIR and SIRS compartmental models and describes how to configure EMOD, an agent-based stochastic model, to simulate an SIR/SIRS epidemic. In SIR models, individuals in the recovered state gain total immunity to the pathogen; in SIRS models, that immunity wanes over time and individuals can become reinfected. The EMOD generic simulation uses an SEIR-like disease model by default. You can modify the default SEIR model to an SIR model by turning off the incubation period.

The SIR/SIRS diagram below shows how individuals move through each compartment in the model. The dashed line shows how the SIR model becomes an SIRS (Susceptible - Infectious - Recovered - Susceptible) model, where recovery does not confer lifelong immunity, and individuals may become susceptible again.

_images/SIR-SIRS.png

SIR - SIRS model

The infectious rate, \(\beta\), controls the rate of spread which represents the probability of transmitting disease between a susceptible and an infectious individual. Recovery rate, \(\gamma\) = 1/D, is determined by the average duration, D, of infection. For the SIRS model, \(\xi\) is the rate which recovered individuals return to the susceptible statue due to loss of immunity.

For a detailed comparison of how the SIR ordinary differential equation (ODE) can be rewritten in the stochastic EMOD model, see Compartmental models and EMOD.

SIR model

The SIR model was first used by Kermack and McKendrick in 1927 and has subsequently been applied to a variety of diseases, especially airborne childhood diseases with lifelong immunity upon recovery, such as measles, mumps, rubella, and pertussis. S, I and R represent the number of susceptible, infected, and recovered individuals, and N = S + I + R is the total population.

SIR without vital dynamics

If the course of the infection is short (emergent outbreak) compared with the lifetime of an individual and the disease is non-fatal, vital dynamics (birth and death) can be ignored. In the deterministic form, the SIR model can be written as the following ordinary differential equation (ODE):

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N}\\ \frac{dI}{dt} & = \frac{\beta SI}{N} - \gamma I\\ \frac{dR}{dt} & = \gamma I \end{aligned}\end{split}\]

where \(N = S + I + R\) is the total population.

In a closed population with no vital dynamics, an epidemic will eventually die out due to an insufficient number of susceptible individuals to sustain the disease. Infected individuals who are added later will not start another epidemic due to the lifelong immunity of the existing population.

The following graphs show the inset chart and charts for all channels in a typical SIR outbreak. To run this example simulation, see the Generic/SIR scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information.

_images/SIR_InsetChart_default.png

Figure 1: Growth of infection and depletion of the susceptible population in an SIR outbreak

_images/SIR_AllCharts_default.png

Figure 2: All output channels for SIR without vital dynamics

SIR with vital dynamics

However in a population with vital dynamics, new births can provide more susceptible individuals to the population, sustaining an epidemic or allowing new introductions to spread throughout the population. In a realistic population like this, disease dynamics will reach a steady state. This is the case when diseases are endemic to a region.

Let \(\mu\) and \(\nu\) represent the birth and death rates, respectively, for the model. To maintain a constant population, assume that \(\mu = \nu\). In steady state \(\frac{dI}{dt} = 0\). The ODE then becomes:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = \mu N -\frac{\beta S I}{N} - \nu S\\ \frac{dI}{dt} & = \frac{\beta S I}{N} - \gamma I - \nu I\\ \frac{dR}{dt} & = \gamma I - \nu R \end{aligned}\end{split}\]

where \(N = S + I + R\) is the total population.

SIRS model

The SIR model assumes people carry lifelong immunity to a disease upon recovery; this is the case for a variety of diseases. For another class of airborne diseases, for example seasonal influenza, an individual’s immunity may wane over time. In this case, the SIRS model is used to allow recovered individuals to return to a susceptible state.

SIRS without vital dynamics

If there is sufficient influx to the susceptible population, at equilibrium the dynamics will be in an endemic state with damped oscillation. The ODE then becomes:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N} + \xi R\\ \frac{dI}{dt} & = \frac{\beta SI}{N} - \gamma I\\ \frac{dR}{dt} & = \gamma I - \xi R \end{aligned}\end{split}\]

where \(N = S + I + R\) is the total population.

EMOD simulates waning immunity by a delayed exponential distribution. Individuals stay immune for a certain period of time then immunity wanes following an exponential distribution. For more information, see Immunity parameters.

The graphs below show damped oscillation due to people losing immunity and becoming susceptible again.

Note

Individuals who are susceptible people due to waning immunity are not classified as susceptible in the simulation. They are reported under the “Waning Population” channel.

_images/SIRS_InsetChart_default.png

Figure 3: Damped oscillation in SIRS outbreak

_images/SIRS_AllCharts_default.png

Figure 4: All output channels for SIRS without vital dynamics

To run this example simulation, see the Generic/SIRS scenario in the EMOD scenarios zip file. Review the README files there for more information.

SIRS with vital dynamics

You can also add vital dynamics to an SIRS model, where \(\mu\) and \(\nu\) again represent the birth and death rates, respectively. To maintain a constant population, assume that \(\mu = \nu\). In steady state \(\frac{dI}{dt} = 0\). The ODE then becomes:

\[\begin{split}\frac{dS}{dt} & = \mu N -\frac{\beta S I}{N} + \xi R - \nu S\\ \frac{dI}{dt} & = \frac{\beta S I}{N} - \gamma I - \nu I\\ \frac{dR}{dt} & = \gamma I - \xi R - \nu R\end{split}\]

where \(N = S + I + R\) is the total population.

SEIR and SEIRS models

This topic describes the differential equations that govern the classic deterministic SEIR and SEIRS compartmental models and describes how to configure EMOD, an agent-based stochastic model, to simulate an SEIR/SEIRS epidemic. In this category of models, individuals experience a long incubation duration (the “exposed” category), such that the individual is infected but not yet infectious. For example chicken pox, and even vector-borne diseases such as dengue hemorrhagic fever have a long incubation duration where the individual cannot yet transmit the pathogen to others.

The SEIR/SEIRS diagram below shows how individuals move through each compartment in the model. The dashed line shows how the SEIR model becomes an SEIRS (Susceptible - Exposed - Infectious - Recovered - Susceptible) model, where recovered people may become susceptible again (recovery does not confer lifelong immunity). For example, rotovirus and malaria are diseases with long incubation durations, and where recovery only confers temporary immunity.

_images/SEIR-SEIRS.png

SEIR - SEIRS model

The infectious rate, \(\beta\), controls the rate of spread which represents the probability of transmitting disease between a susceptible and an infectious individual. The incubation rate, \(\sigma\), is the rate of latent individuals becoming infectious (average duration of incubation is 1/\(\sigma\)). Recovery rate, \(\gamma\) = 1/D, is determined by the average duration, D, of infection. For the SEIRS model, \(\xi\) is the rate which recovered individuals return to the susceptible state due to loss of immunity.

SEIR model

Many diseases have a latent phase during which the individual is infected but not yet infectious. This delay between the acquisition of infection and the infectious state can be incorporated within the SIR model by adding a latent/exposed population, E, and letting infected (but not yet infectious) individuals move from S to E and from E to I. For more information, see Incubation parameters.

SEIR without vital dynamics

In a closed population with no births or deaths, the SEIR model becomes:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N}\\ \frac{dE}{dt} & = \frac{\beta SI}{N} - \sigma E\\ \frac{dI}{dt} & = \sigma E - \gamma I\\ \frac{dR}{dt} & = \gamma I \end{aligned}\end{split}\]

where \(N = S + E + I + R\) is the total population.

Since the latency delays the start of the individual’s infectious period, the secondary spread from an infected individual will occur at a later time compared with an SIR model, which has no latency. Therefore, including a longer latency period will result in slower initial growth of the outbreak. However, since the model does not include mortality, the basic reproductive number, R0 = \(\beta/\gamma\), does not change.

The complete course of outbreak is observed. After the initial fast growth, the epidemic depletes the susceptible population. Eventually the virus cannot find enough new susceptible people and dies out. Introducing the incubation period does not change the cumulative number of infected individuals.

The following graphs show the inset chart and charts for all channels in a couple typical SEIR outbreaks, one with an incubation period of 8 days and one with an incubation period of 2 days. Notice how the outbreak depletes the susceptible population more quickly when the incubation period is shorter but that the cumulative infections remains the same. To run this example simulation, see the Generic/SEIR scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information.

_images/SEIR_InsetChart_default.png

Figure 1: SEIR epidemic course for 8-day incubation period

_images/SEIR_AllCharts_default.png

Figure 2: All output channels for SEIR 8-day incubation period

_images/SEIR_InsetChart_2day.png

Figure 3: SEIR epidemic course for 2-day incubation period

_images/SEIR_AllCharts_2day.png

Figure 4: All output channels for SEIR 2-day incubation period

SEIR with vital dynamics

As with the SIR model, enabling vital dynamics (births and deaths) can sustain an epidemic or allow new introductions to spread because new births provide more susceptible individuals. In a realistic population like this, disease dynamics will reach a steady state. Where \(\mu\) and \(\nu\) represent the birth and death rates, respectively, and are assumed to be equal to maintain a constant population, the ODE then becomes:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = \mu N - \nu S - \frac{\beta SI}{N}\\ \frac{dE}{dt} & = \frac{\beta SI}{N} - \nu E - \sigma E\\ \frac{dI}{dt} & = \sigma E - \gamma I - \nu I\\ \frac{dR}{dt} & = \gamma I - \nu R \end{aligned}\end{split}\]

where \(N = S + E + I + R\) is the total population.

The following graphs show periodic reintroductions of an SEIR outbreak in a population with vital dynamics. To run this example simulation, see the Generic/SEIR_VitalDynamics scenario in the EMOD scenarios folder. Review the README files there for more information.

_images/SEIR_Vital_InsetChart_default.png

Figure 5: SEIR periodic outbreaks on reintroduction in a population with vital dynamics

_images/SEIR_Vital_AllCharts_default.png

Figure 6: All output channels for SEIR outbreaks

SEIRS model

The SEIR model assumes people carry lifelong immunity to a disease upon recovery, but for many diseases the immunity after infection wanes over time. In this case, the SEIRS model is used to allow recovered individuals to return to a susceptible state. Specifically, \(\xi\) is the rate which recovered individuals return to the susceptible statue due to loss of immunity. If there is sufficient influx to the susceptible population, at equilibrium the dynamics will be in an endemic state with damped oscillation. The SEIRS ODE is:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N} + \xi R\\ \frac{dE}{dt} & = \frac{\beta SI}{N} - \sigma E\\ \frac{dI}{dt} & = \sigma E - \gamma I\\ \frac{dR}{dt} & = \gamma I - \xi R \end{aligned}\end{split}\]

where \(N = S + E + I + R\) is the total population.

EMOD simulates waning immunity by a delayed exponential distribution. Individuals stay immune for a certain period of time then immunity wanes following an exponential distribution. For more information, see Immunity parameters.

SEIRS with vital dynamics

You can also add vital dynamics to an SEIRS model, where \(\mu\) and \(\nu\) again represent the birth and death rates, respectively. To maintain a constant population, assume that \(\mu = \nu\). In steady state \(\frac{dI}{dt} = 0\). The ODE then becomes:

\[\begin{split}\frac{dS}{dt} & = \mu N - \frac{\beta S I}{N} + \xi R- \nu S\\ \frac{dE}{dt} & = \frac{\beta S I}{N} - \sigma E - \nu E\\ \frac{dI}{dt} & = \sigma E - \gamma I - \nu I\\ \frac{dR}{dt} & = \gamma I - \xi R - \nu R\end{split}\]

where \(N = S + E + I + R\) is the total population.

The following graphs show the complete trajectory of a fatal SEIRS outbreak: the disease endemicity due to vital process and waning immunity and the effect of vaccination campaigns that eradicate the outbreak after day 500. To run this example simulation, see the Generic/SEIRS scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information. For more information on creating campaigns, see Creating campaigns.

_images/SEIRS_InsetChart_default.png

Figure 7: Trajectory of the SEIRS outbreak

_images/SEIRS_AllCharts_default.png

Figure 8: All output channels for SEIRS outbreak

SI and SIS models

This topic describes the differential equations that govern the classic deterministic SI and SIS compartmental models and describes how to configure EMOD, an agent-based stochastic model, to simulate an SI/SIS epidemic. In SI models, people never leave the infectious state and have lifelong infections. For example, herpes is a disease with lifelong infectiousness.

The SI/SIS diagram below shows how individuals move through each compartment in the model. The dashed line shows how the model becomes an SIS (Susceptible - Infectious - Susceptible) model, where infection does not confer immunity (or there is waning immunity). Individuals have repeat or reoccurring infections, and infected individuals return to the susceptible state. For example, sexually transmitted diseases such as gonorrhea or chlamydia fall into this group.

_images/SI-SIS.png

SI - SIS model

The infectious rate, \(\beta\), controls the rate of spread which represents the probability of transmitting disease between a susceptible and an infectious individual. Recovery rate, \(\gamma\) = 1/D, is determined by the average duration, D, of infection.

SI model

The SI model is the simplest form of all disease models. Individuals are born into the simulation with no immunity (susceptible). Once infected and with no treatment, individuals stay infected and infectious throughout their life, and remain in contact with the susceptible population. This model matches the behavior of diseases like cytomegalovirus (CMV) or herpes.

SI without vital dynamics

The dynamics of I in a SI model are also known as logistic growth. If there are no vital processes (birth and death), every susceptible will eventually become infected. The EMOD generic simulation uses an SEIR model by default. However, it can be modified to an SI model by turning off incubation and setting the infectious period to be longer than a human lifespan.

The SI model can be written as the following ordinary differential equation (ODE):

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N}\\ \frac{dI}{dt} & = \frac{\beta SI}{N} = \beta I \left(1-\frac{I}{N}\right) \end{aligned}\end{split}\]

where \(N = S + I\) is the total population.

The following graphs show the inset chart and charts for all channels in an SI simulation without vital dynamics. To run this example simulation, see the Generic/SI scenario in the downloadable EMOD scenarios folder and set Enable_Vital_Dynamics to 0. Review the README files there for more information.

_images/SI_InsetChart_vitaloff.png

Figure 1: SI outbreak showing logistic grown

_images/SI_AllCharts_vitaloff.png

Figure 2: All output channels for an SI outbreak

SI with vital dynamics

To add vital dynamics to a population, let \(\mu\) and \(\nu\) represent the birth and death rates, respectively, for the model. To maintain a constant population, assume that \(\mu = \nu\). Therefore, the ODE becomes:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = \mu N - \frac{\beta SI}{N} - \nu S\\ \frac{dI}{dt} & = \frac{\beta SI}{N} - \nu I \end{aligned}\end{split}\]

where \(N = S + I\) is the total population.

The final proportion of infected people is related to both the vital dynamics and \(\beta\). \(\beta\) can be calculated by looking at the steady state:

\[\mu = \nu = \frac{\beta S}{N} = \beta \left(1 - \frac{I}{N}\right)\]

The following graphs show the inset chart and charts for all channels in the Generic/SI scenario when vital dynamics remains on. The anticipated final epidemic size, \(I/N\), is 85%, and the birth and death rate equals 0.0000548 per day (2% per year). Therefore, \(\beta\) = 0.00003653.

_images/SI_InsetChart_default.png

Figure 3: SI outbreak approaching 85% infected population at steady state

_images/SI_AllCharts_default.png

Figure 4: All output channels for an SI outbreak with vital dynamics

SIS

Similar to the SIRS model, the infected individuals return to the susceptible state after infection. This model is appropriate for diseases that commonly have repeat infections, for example, the common cold (rhinoviruses) or sexually transmitted diseases like gonorrhea or chlamydia.

The generic simulation type uses an SEIR model by default. However, it can be modified to an SIS model by configuration no incubation period and no immunity. For more information, see Incubation and Immunity parameters.

SIS without vital dynamics

Because individuals remain susceptible after infection, the disease attains a steady state in a population, even without vital dynamics. The ODE for the SIS model without vital dynamics can be analytically solved to understand the disease dynamics. The ODE is as follows:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N} + \gamma I\\ \frac{dI}{dt} & = \frac{\beta SI}{N} - \gamma I\\ \end{aligned}\end{split}\]

At equilibrium, solving:

\[\frac{dI}{dt} = \beta I \left(1-\frac{I}{N}\right) - \gamma I = 0\]

There are two equilibrium states for the SIS model, the first is \(I = 0\) (disease free state), and the second is:

\[I = \frac{(\beta - \gamma)N}{\beta} = \left(1-\frac{\gamma}{\beta}\right)N\]

For disease to spread, \(dI/dt > 0\). Therefore, similar to the previously described concept of the basic reproductive number, when \(\beta/\gamma > 1\), the disease will spread and approach the second steady state; otherwise, it will eventually reach the disease-free state.

The following graphs show the inset chart and charts for all channels in an SIS simulation without vital dynamics that eventually approaches steady state. You can compare the fraction of infected people with the anticipated value based on the previous calculation. If we have a reproductive number of 1.2, the infected fraction at equilibrium will be 1 - (1/1.2) ~ 17%.

To run this example simulation, see the Generic/SIS scenario in the EMOD scenarios zip file. Review the README files there for more information.

_images/SIS_InsetChart_default.png

Figure 5: SIS outbreak approaching 17% infected population at steady state

_images/SIS_AllCharts_default.png

Figure 6: All output channels for an SIS outbreak without vital dynamics

SIS with vital dynamics

To add vital dynamics to a population, let \(\mu\) and \(\nu\) represent the birth and death rates, respectively, for the model. To maintain a constant population, assume that \(\mu = \nu\). Therefore, the ODE becomes:

\[\begin{split}\frac{dS}{dt} & = \mu N -\frac{\beta S I}{N} + \gamma I - \nu S\\ \frac{dI}{dt} & = \frac{\beta S I}{N} - \gamma I - \nu I\end{split}\]
Disease outbreaks, reservoirs, and endemicity

To configure disease outbreaks in EMOD simulations, you have a few different options. Generally, you will configure an outbreak event to occur at some point during the simulation. For zoonotic diseases, you can also introduce the disease through an animal reservoir.

Outbreak events

Somewhat counter-intuitively, disease outbreaks are configured as “interventions” in the campaign file. While the demographics and configuration files specify consistent qualities of the population or disease, the campaign file is organized into events that occur during the course of the simulation. Most of these events trigger disease interventions such as vaccinations and diagnostic tests, but the outbreak is included here as well. Like other interventions, outbreaks are nested within event coordinators and events, which control when, where, and within which demographic the outbreak occurs. For more information, see Creating campaigns.

The two available classes for including a disease outbreak are:

OutbreakIndividual

This intervention infects existing individuals with a specified disease. You can configure the outbreak to occur in individuals that meet certain criteria, such as being high risk.

Outbreak

This intervention adds new infected individuals to a node or infects existing individuals. You cannot specify the demographics of these individuals because the outbreak is at the node level.

Because of the ability to target outbreaks to specific individuals, OutbreakIndividual is much more commonly used. However, you can use either type of outbreak for the scenarios described below.

Emergent outbreak

In a population where the disease is not endemic, you will generally include one outbreak in the campaign file. If the population is naive (no immunity), the disease will likely spread. If the population has immunity, it may not. Immunity may be due to vaccination or, if the disease was recently endemic, prior infection.

For an example of the effect of vaccination on herd immunity and the spread of an outbreak, see Creating campaigns.

Endemic disease

If the disease is endemic to a region, outbreaks can be periodically repeated to simulate regular occurrences of the disease in the population. There will likely be some level of immunity within the population when a disease is endemic.

Alternatively, you can run a simulation for a period of time until the disease dynamics reach a steady state and disregard simulation output prior to that point. This is known as simulation burn-in, a modeling concept borrowed from the electronics industry where the first items produced by a manufacturing process are discarded. EMOD enables you to then serialize the population state at this point so you can reload in subsequent simulations to analyze the effect of interventions on an endemic disease. See Simulation setup for serialization parameters.

Infectivity reservoirs

You can also introduce outbreaks through infectivity reservoirs; for example, zoonotic diseases may have a background animal reservoir that continuously exposes humans to infection. Zoonotic diseases are of particular interest because typically they have not previously been in the human population, making the whole population susceptible.

To configure a simulation with an infectivity reservoir, you must enable the configuration parameter Enable_Infectivity_Reservoir and configure the demographics parameter InfectivityReservoirSize. You may also use and configure the demographics parameters InfectivityReservoirStartTime and InfectivityReservoirEndTime.

The rate of reservoir-to-human transmission is configured with the parameter InfectivityReservoirSize and human-to-human transmission by the Infectivity and transmission parameters. These values can be adjusted to shift the disease from a low rate of primary zoonotic infection with substantial secondary human transmission to a high zoonosis rate with low human transmission. This changes the fraction of cases that are primary zoonotic infections.

The following graphs show the inset chart and charts for all channels in an outbreak of a zoonotic disease. To run this example simulation, see the Generic/Zoonosis scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information.

After the initial outbreak, there are no additional imported cases set in the campaign file. However, there are additional introductions from the animal reservoir, as shown in the log prevalence chart.

_images/Zoonosis_InsetChart_default.png

Figure 1: Zoonotic disease outbreak and animal reservoir

_images/Zoonosis_AllCharts_default.png

Figure 2: All output channels showing re-seeding caused by zoonosis and waning immunity

Adding heterogeneity

One of the benefits of an agent-based model like EMOD over compartmental models is that the the model can be configured to capture heterogeneity in population demographics, migration patterns, disease transmissibility, climate, interventions, and more. This heterogeneity can affect the overall course of the disease outbreak and campaign interventions aimed at controlling it.

Demographics

Built-in demographics options are available for running EMOD simulations, or you can create customized demographics files to represent particular locations. It is generally recommended that you create a demographics file instead of using built-in demographics.

Every individual within the simulation has a variety of attributes, represented by continuous or discrete state variables. Some are static throughout life, and others dynamically change through the course of the simulation, through response either to aging or to simulation events (such as infection). Static attributes are assigned upon instantiation (simulation initialization or birth after the beginning of the simulation) and include gender, time of birth, time of non-disease death, etc. Dynamic attributes include disease state, history of interventions, and more.

Vital dynamics

Vital dynamics within EMOD are derived from fertility and mortality tables that are passed to the model as input. Input demographic data can be used to construct a cumulative probability distribution function (CDF) of death date based on individuals’ birth dates. Then, in the model, individual agents will be sampled stochastically from this CDF using an inverse transform of this distribution. Female agents similarly sample the age at next childbirth, if any, upon instantiation and birth of a previous child. Pregnancy is not linked to relationship status, although newly born individuals are linked to a mother. The fertility rate changes by simulation year and female age, and the range for available estimates depends on input data. Values outside of this range can be chosen by “clamping,” or choosing the nearest value within the range. Clamping was also used when necessary to determine the non-disease mortality rate, which varies by gender, age, and simulation year.

For more information on the demographics file, see Demographics file.

Individual and node properties

One of the most powerful and flexible features of EMOD is the ability to assign properties to nodes or individuals that can then be used to target interventions or move individuals through a health care system. For example, you might assign various degrees of risk, socioeconomic status, intervention status, and more. In the generic, environmental, typhoid, airborne, and TBHIV simulation types, these properties can be leveraged to add heterogeneity in transmission based on the property values assigned to each individual. For example, you might configure higher transmission among school-age children.

Similarly, you can add properties to nodes in a simulation. For example, you might configure some regions to be more urban or rural, to have better health care, or to be difficult to access by health care workers. This feature of EMOD is known as Heterogeneous Intra-Node Transmission (HINT); for more information, see Property-based heterogeneous disease transmission (HINT) and Multi-route HINT.

Transmission

By default, EMOD assumes transmission is homogeneous in each node: transmission does not vary based on population density, the population is “well-mixed” in each node, each individual has an equal likelihood of transmitting or contracting a disease. However, all of these aspects can be configured for greater heterogeneity to more accurately simulate a realistic population and disease dynamics. One simple example is varying transmission rates based on population density.

Other EMOD simulation types capture heterogeneous transmission through more biologically mechanistic parameters that control aspects of the simulation such as parasite density, symptom severity, coital acts, and more. Review the model overview for those simulation types for more information.

Migration

EMOD can also simulate human and vector migration, which can be important in the transmission of many diseases. You can assign different characteristics to each geographic node to control how the disease spreads.

For more information on how you can target campaign interventions to individuals or locations based on certain criteria, see Creating campaigns.

Population density and transmission scaling

Disease transmission depends on the rate effective contacts as represented by parameter \(\beta_0\). But what happens to the effective contact rate as the size of the population changes? There are two commonly accepted answers: frequency-dependent and density-dependent transmission scaling.

Frequency-dependent scaling

By default, EMOD uses frequency-dependent transmission and the overall transmissibility does not change with population size or density. An infected individual will infect the same number of people either in a small village or in a metropolitan area. For this case,

\[\text{Transmission} \propto \frac{\text{Number of effective contacts per unit time}}{\text{Current size of the node population}},\]

so that the transmission rate inversely proportional to \(N(t)\). The dynamics are frequency- dependent because the \(\beta_0\) parameter is divided by the current node population, \(N(t)\).

Density-dependent scaling

However, when population size is low it’s possible that the transmissibility might be lower and follow density-dependent behavior. Think of a room containing \(N\) individuals. A single highly-infectious cough would infect more people if the number of people in the room (population density) was higher. The number of effective contacts per person per time is proportional to the population. For this case,

\[\text{Transmission} \propto \frac{\text{Number of effective contacts per unit time}}{\text{Fixed population size}},\]

Usually, the denominator is taken as \(N(t=0)\), the initial node population. Note that the transmission rate per capita is a constant in this case. Density-dependent transmission is often found in SIR models, which inherently neglect the total population size.

Saturating function of population density

Based on existing evidence, it is possible that neither a frequency-dependent nor a density- dependent mechanism may adequately describe the correct scaling over the entire population density spectrum, but that more closely follows a non-linear scaling function. That is, contact rates tend to increase with density but saturate at high densities. EMOD allows the transmission rate to scale as a saturating function of population density. The force of infection contributed by each infected individual under these two cases of transmission scaling are as follows:

\[\begin{split}\text{Force per infected} = \left\{ \begin{array}{ll} \frac{\beta_0}{N} & \text{Frequency dependence} \\ \left[1 - \exp\left(- \frac{\rho}{\rho_{50}}\right)\right] \frac{\beta_0}{N} & \text{Saturating function of density} \end{array} \right.\end{split}\]

Here, \(\rho\) is the population density and \(\rho_{50}\) is an input parameter the governs the transition from density to frequency dependence. The population density is computed as \(\rho =\frac{N}{A}\) where \(A\) is is the area of the node. This node area is in turn computed from the longitude and latitude of the node center point (from the demographics file) and the node size. It is assumed that all nodes have equal size in terms of the degrees of latitude and longitude, as determined by configuration parameter Node_Grid_Size. Denoting this node grid size by \(w\), the area of a node located at (lat, long) is computed based on the corresponding area of a sphere,

\[A = R^2\Big\lbrace\Big[\text{cos}\Big(\Big(90-\text{lat}-\frac{w}{2}\Big)\frac{\pi}{180}\Big)- \text{cos}\Big(\Big(90-\text{lat}+\frac{w}{2}\Big)\frac{\pi}{180}\Big)\Big]\frac{w\pi}{180}\Big\rbrace,\]

where \(R=6371.2213\) km is the radius of Earth.

The saturating function of density is enabled by setting the EMOD configuration parameter Population_Density_Infectivity_Correction to SATURATING_FUNCTION_OF_DENSITY. Finally, the \(\rho_{50}\) parameter is configured using the configuration parameter Population_Density_C50. For more information, see Infectivity and transmission parameters.

This is described in more detail in the article The scaling of contact rates with population density for the infectious disease models, by Hu et al., 2013 Mathematical Biosciences. 244(2):125-134. See the figure from that article below.

_images/DensityScaling_orig_cropped.png

Figure 1: Effect of population density on transmissibility

The Generic/DensityScaling example scenario in the EMOD scenarios zip file illustrates how population density can be configured to affect transmission. Review the README files there for more information.

The table below shows how setting Node_Grid_Size in that scenario to 0.1, 0.15, and 0.3 affects population density and R0 values.

Simulation

Population

Latitude, Longitude

Node_Grid_Size

Node Area

Density

R0

1

10,000

0, 0

0.1

124

80

R0> 1

2

10,000

0, 0

0.15

278

36

R0~ 1

3

10,000

0, 0

0.3

1112

9

R0< 1

The following graphs show the effect of population density on transmissibility, in terms of maintaining endemic status. When population density is large enough, it is easy to maintain an endemic status while in lower density is difficult to do so.

_images/Density_default.png

Figure 2: Node_Grid_Size = 0.1, population density 80/km2and R0 > 1

_images/Density_15.png

Figure 3: Node_Grid_Size = 0.15, population density 36/km2and R0 ~ 1

_images/Density_3.png

Figure 4: Node_Grid_Size = 0.3, population density 9/km2and R0 < 1

Individual and node properties

One of the strengths of an agent-based model, as opposed to a compartmental model governed by ODEs, is that you can introduce heterogeneity in individuals and regions. For example, you can define property values for accessibility, age, geography, risk, and other properties and assign these values to individuals or nodes in the simulation.

These properties are most commonly used to target (or avoid targeting) particular nodes or individuals with interventions. For example, you might want to put individuals into different age bins and then target interventions to individuals in a particular age bin. Another common use is to configure treatment coverage to be higher for nodes that are easy to access and lower for nodes that are difficult to access. For more information on creating campaign interventions, see Creating campaigns.

For some simulation types, you can also configure heterogeneous transmission between individuals with different property values. For more information, see Property-based heterogeneous disease transmission (HINT) and Multi-route HINT. For other simulation types, transmission is configured using mechanistic parameter settings, such as parasite density, viral load, biting frequency, and other measures relevant to the disease being modeled. See Infectivity and transmission for more information.

The following sections describe how to define individual properties and assign different values to individuals in a simulation. However, with the exception of setting up age bins, you can use the same process to assign properties to a node. To see all individual and node property parameters, see NodeProperties and IndividualProperties.

Create individual properties other than age

Assigning property values to individuals uses the IndividualProperties parameter in the demographics file. See Demographics parameters for a list of supported properties. The values you assign to properties are user-defined and can be applied to individuals in all nodes or only in particular nodes in a simulation.

Note that although EMOD provides several different properties, such as risk and accessibility, these properties do not add logic, in and of themselves, to the simulation. For example, if you define individuals as high and low risk, that does not add different risk factors to the individuals. Higher prevalence or any other differences must be configured separately. Therefore, the different properties are merely suggestions and can be used to track any property you like.

  1. In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the values to apply to all nodes, add it in the Defaults section; if you want the values to be applied to specific nodes, add it to the Nodes section.

  2. In the array, add an empty JSON object. Within it, do the following:

    1. Add the Property parameter and set it to one of the supported values.

    2. Add the Values parameter and set it to an array of possible values that can be assigned to individuals. You can define any string value here.

    3. Add the Initial_Distribution parameter and set it to an array of numbers that add up to 1. This configures the initial distribution of the values assigned to individuals in one or all nodes.

  3. If you want to add another property and associated values, add a new JSON object in the IndividualProperties array as above.

Note

Multiple properties must be defined in one file. They can be defined in either the base layer demographics file or an overlay file, but they cannot be split between the files. The maximum number of property types that can be added is two.

Create properties for age ranges

Creating properties based on age ranges works a little differently than other properties. Age_Bin is tied to the simulated age of an individual rather than being an independent property. Some of its characteristics, such as initial distribution and transitions, are dependent on information from the demographics file and EMOD that manages individual aging during the simulation.

  1. In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the values to apply to all nodes, add it in the Defaults section; if you want the values to be applied to specific nodes, add it to the Nodes section.

  2. In the array, add an empty JSON object. Within it, do the following:

    1. Add the Property parameter and set it to “Age_Bin”.

    2. Add the Age_Bin_Edges_In_Years parameter and set it to an array that contains a comma- delimited list of integers in ascending order that define the boundaries used for each of the age bins, in years. The first number must always be 0 (zero) to indicate the age at birth and the last number must be -1 to indicate the maximum age in the simulation.

The example below shows how to set up several property values based on disease risk and physical place. It also defines three age bins: 0 to 5 years, older than 5 to 13, and older than 13 to the maximum age.

{
    "Defaults": {
        "IndividualProperties": [{
            "Property": "Risk",
            "Values": ["Low", "Medium", "High"],
            "Initial_Distribution": [0.7, 0.2, 0.1]
        }, {
            "Property": "Place",
            "Values": ["Community", "School", "Work", "Vacation"],
            "Initial_Distribution": [0.3, 0.2, 0.4, 0.1]
        }, {
            "Property": "Age_Bin",
            "Age_Bin_Edges_In_Years": [0, 5, 13, -1],
            "Transitions": []
        }]
    }
}

For an example of a complete demographics file with individual properties set, see the demographics file used in the 11_HINT_AgeAndAccess scenario. This scenario is described in more detail in Property-based heterogeneous disease transmission (HINT).

Property-based heterogeneous disease transmission (HINT)

Only generic, environmental, typhoid, airborne, or TBHIV simulations can use Heterogeneous Intra-Node Transmission (HINT) to manually configure heterogeneous disease transmission within each node. All other simulation types have preconfigured solutions for heterogeneous disease transmission based on the biological processes of the disease being modeled. For example, you can set parameters for parasite density, viral load, mosquito bites, and other relevant transmission factors.

See Infectivity and transmission parameters for more information on configuring transmission in this simulation type. Because HINT cannot be used with this simulation type, the parameter Enable_Heterogeneous_Intranode_Transmission in the configuration file must be set to 0 (zero).

Multi-route HINT

Only simulations using the environmental model (or inherited from environmental, such as typhoid) can use Heterogeneous Intra-Node Transmission (HINT) or Multi-route HINT to configure heterogeneous disease transmission within each node and across multiple routes of exposure. Generic, airborne, or TBHIV simulations can only use Heterogeneous Intra-Node Transmission (HINT) for contact-based transmission, and all other simulation types have preconfigured solutions for heterogeneous disease transmission based on the biological processes of the disease being modeled. For example, you can set parameters for parasite density, viral load, mosquito bites, and other relevant transmission factors.

See Infectivity and transmission parameters for more information on configuring transmission in this simulation type.

Geographic migration

Human migration is a important factor in the spread of disease across a geographic region. EMOD represents geography using nodes. Migration occurs when individuals move from one node to another; disease transmission occurs within nodes. Therefore, infected individuals can migrate to nodes without disease and introduce disease transmission into that node. Nodes are very flexible and can represent everything from individual households to entire countries or anything in between. Therefore, to include migration in a simulation, you must define multiple nodes.

At each time step, individuals in each node have a defined probability of migrating out of their current node to another. You can also define the average length of time individuals will stay in their destination node before migrating again. If you are using timesteps longer than one day and the time to next migration falls between timesteps, individuals will migrate at the following timestep. For example, if you use 7-day timesteps and an individual draws a 12-day trip duration, they won’t migrate until day 14.

The mode of migration can be local (foot travel), regional (by roadway or rail), by air, or by sea. You can also define different migration patterns, such as one-way or roundtrip. Individuals have a “home node” that is relevant for some types of migration, such as migrating an entire family unit only when all members are home or returning home after passing through several waypoints. For more detailed information, see Migration parameters.

For STIs including HIV, you can specify the consequence of migration on an individual’s existing relationship. For example, you may configure the simulation such that an individual’s partner will migrate with them for marital relationships, but the relationship will be terminated for informal relationships.

You must include a separate migration file for each mode of travel that describes the migration patterns for each node. It lists the migration rate for each node. Migration rate is defined as the fraction of the node’s population that is migrating out of the node per day. Units are per person per day, meaning the number of people migrating per day divided by the total population of the node. For more information on the structure of these files, see Migration files.

The Generic/Zoonosis scenario in the downloadable EMOD scenarios zip file includes daily migration. Review the README files there for more information.

Creating campaigns

You define the initial disease outbreak and interventions used to combat it for a simulation through a JSON-formatted campaign file, typically called campaign.json. It is hierarchically organized into logical groups of parameters that can have multiple levels of nesting. It contains an Events array of campaign events, each of which contains a JSON object describing the event coordinator, which in turn contains a nested JSON object describing the intervention. Campaign events determine when and where an intervention is distributed, event coordinators determine who receives the intervention, and interventions determine what is actually distributed. For example, a vaccination or diagnostic test.

Interventions can be targeted to particular nodes or individuals, based on age or other characteristics. Additionally, you can structure campaigns to guide individuals through complex health care systems. For example, administering a second-line treatment only after the preferred treatment has proven ineffective for an individual.

For some interventions, there can be a very complex hierarchical structure, including recursion. This framework enables rigorous testing of possible control strategies to determine which events or combination of events will best aid in the elimination of disease for specific geographic locations.

Multiple interventions

When creating multiple interventions, either of the same type or different types, they will generally be distributed independently without regard to whether a person has already received another intervention.

For example, say you create two SimpleBednet interventions and both interventions have Demographic_Coverage set to 0.5 (50% demographic coverage). This value is the probability that each individual in the target population will receive the intervention. It does not guarantee that the exact fraction of the target population set by Demographic_Coverage receives the intervention.

By default, each individual in the simulation will have a 50% chance of receiving a bednet in both of the distributions and the two distributions will be independent. Therefore, each individual has a 75% chance of receiving at least one bednet.

_images/howto-multiple.png
Campaign file overview

For the interventions to take place, the campaign file must be in the same directory as the configuration file and you must set the configuration parameters Enable_Interventions to 1 and Campaign_Filename to the name of the campaign file. When you run a simulation, you must have a single campaign file. However, you can use a campaign overlay file that includes certain parameters of interest that will override the settings in a base file; these files must be flattened into a single file before running a simulation. See Campaign overlay files for more information flattening two campaign files.

Although you can create campaign files entirely from scratch, it is often easier to start from an existing campaign file and modify it to meet your needs. The simplest method is to edit the parameters or parameter values in the JSON file in any text editor. You may also create or modify the files using a scripting language, as with configuration files. See Example scripts to modify a configuration file for a couple examples.

The following is an example of campaign file that has two events (SimpleVaccine and Outbreak) that occur in all nodes at day 1 and day 30, respectively. Each event contains an event coordinator that describes who receives the intervention (everyone, with the vaccine repeated three times) and the configuration for the intervention itself. Note that the nested JSON elements have been organized to best illustrate their hierarchy, but that many files in the Regression directory list the parameters within the objects differently. See Campaign parameters for more information on the structure of these files and available parameters for this simulation type.

{
    "Campaign_Name": "Vaccine",
    "Use_Defaults": 1,
    "Events":
    [
        {
            "Event_Name": "SimpleVaccine",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 1,
            "class": "CampaignEvent",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.5,
                "Number_Repetitions": 3,
                "Target_Demographic": "Everyone",
                "Timesteps_Between_Repetitions": 7,
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "Cost_To_Consumer": 10,
                    "Waning_Config": {
                        "class": "WaningEffectMapLinear",
                        "Initial_Effect" : 1.0,
                        "Expire_At_Durability_Map_End" : 0,
                        "Durability_Map" : {
                            "Times"  : [   0,  30,  60,  90, 120 ],
                            "Values" : [ 0.9, 0.3, 0.9, 0.6, 1.0 ]
                        }
                    },
                    "Vaccine_Take": 1,
                    "Vaccine_Type": "AcquisitionBlocking",
                    "class": "SimpleVaccine"
                }
            },
        },
        {
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "Antigen": 0,
                    "Genome": 0,
                    "Outbreak_Source": "PrevalenceIncrease",
                    "class": "OutbreakIndividual"
                }
            }
        }
    ]
}

For a complete list of campaign parameters that are available to use with this simulation type and more detail about the campaign file structure, see Campaign parameters. For more information about JSON, see EMOD parameter reference.

Targeting interventions to nodes or individuals

Generally, you want to target your outbreaks and campaign interventions to specific regions or individuals who meet certain criteria. For example, you may want to distribute bednets only to areas where a mosquito-borne disease is endemic or vaccinate only young children who are at highest risk of a disease like measles. This topic describes how to distribute interventions to specific geographic nodes or groups of individuals.

Target to nodes based on geography

Targeting geographic nodes with a particular intervention can be controlled by the Nodeset_Config parameter in the campaign event. You can configure the event to target all nodes, a list of nodes, or all nodes contained within a defined polygon. For more information, see CampaignEvent.

Target to nodes or individuals using properties

To target interventions to particular individuals or nodes based on their property values, you must first define those properties in the demographics file using IndividualProperties or NodeProperties. See NodeProperties and IndividualProperties parameters for more information. Then, in the event coordinator in the campaign file, you can target an intervention or outbreak to particular individuals or nodes based on the properties applied to them. You can target the intervention based on one or more combinations of property values. For example, you may target individuals who are both medium risk and easily accessible or high risk and easily accessible. See Events and event coordinators for all available event coordinators.

Just as defining properties based on age works a little differently than other properties, targeting an intervention to a particular age range works a little differently than targeting an intervention to other properties. Note that not all event coordinators support all of these options.

To target interventions to node properties, use the Node_Property_Restrictions parameter to list the node property key-value pairs that must be assigned to a node for it to receive the intervention.

To target interventions to individual properties, use the Property_Restrictions_Within_Node parameter to list the individual property key-value pairs that must be assigned to a node for it to receive the intervention. You may instead use the Property_Restrictions parameter, but it does not support and/or combinations of multiple property values.

To target interventions to age ranges use the Target_Demographic parameter. This parameter also enables targeting based on gender, migration status, women of childbearing age, and other characteristics.

For more information on the specific parameter values and syntax, see individual event coordinators documented in Events and event coordinators.

Illustrated examples

The following examples illustrate how to target interventions to different groups. This includes how to configure interventions when there are multiple relevant properties, such as targeting individuals who are both low-risk and in a suburban setting or individuals who are either low- risk or living in suburban settings.

Single property, single value

The following examples show how to target interventions based on a single property value.

This example restricts the intervention to urban individuals.

{
    "Property_Restrictions_Within_Node": [
        { "Place": "Urban" }
    ]
}
_images/howto-targeted-1.png

Even if you have multiple properties defined in the demographics file, you can target interventions to a single property value in the same way. Individuals can be assigned any of the values for the other property types.

In this example, the intervention targets suburban individuals, regardless of their risk.

{
    "Property_Restrictions_Within_Node": [
        { "Place": "Suburban" }
    ]
}
_images/howto-targeted-2.png
Single property, multiple values

If you want to individuals with multiple values for the same property type, list the key/value pairs as separate objects in the array.

In this example, the intervention targets both rural and urban individuals.

{
  "Property_Restrictions_Within_Node": [
      { "Place": "Rural" },
      { "Place": "Urban" }
  ]
}
_images/howto-targeted-3.png
Multiple properties, individuals must match all values

To target individuals who match particular values defined by multiple property types, list the key/value pairs in the same object. This is an AND combination.

In this example, a intervention is targeted at low risk, suburban individuals. Individuals must have both property values.

{
  "Property_Restrictions_Within_Node": [
      { "Risk": "Low", "Place": "Suburban" }
  ]
}
_images/howto-targeted-4.png
Multiple properties, individuals must match at least one value

However, if you want to target multiple properties, but individuals need to have only one of the specified values to qualify for the intervention, list the key/value pairs as separate objects. This is an OR combination.

In this example, the intervention is targeted at individuals who are either low risk or suburban.

{
  "Property_Restrictions_Within_Node": [
      {"Risk": "Low"},
      { "Place": "Suburban" }
  ]
}
_images/howto-targeted-5.png
Target an age range

Targeting an intervention to an age range is configured differently than targeting an intervention to other property types. You have a couple different options.

When individuals must match for both age AND another property, you can use Target_Demographic to limit the age range. To use this method to cover multiple segments using an OR combination requires you to configure multiple campaign events to cover each segment of the population.

In this example, the intervention is targeted at urban individuals who are also age 0 to 5.

{
    "Property_Restrictions_Within_Node": [
        { "Place": "Urban" }
    ],
    "Target_Demographic": "ExplicitAgeRanges",
    "Target_Age_Min": 0,
    "Target_Age_Max": 5
}
_images/howto-targeted-6.png

However, to create property value criteria in AND/OR combinations as above, you can use the Age_Bin property with Property_Restrictions_Within_Node instead. EMOD automatically creates Age_Bin_Property_From_X_To_Y values when you use the Age_Bin_Edges_In_Years demographics parameter.

In this example, the intervention is targeted at individuals 0-5 who are low risk, 5-13 who are medium risk, or 13-125 who are high risk.

{
    "Property_Restrictions_Within_Node": [{
            "Risk": "LOW",
            "Age_Bin": "Age_Bin_Property_From_0_To_5"
        },
        {
            "Risk": "MEDIUM",
            "Age_Bin": "Age_Bin_Property_From_5_To_13"
        },
        {
            "Risk": "HIGH",
            "Age_Bin": "Age_Bin_Property_From_13_To_125"
        }
    ]
}

The following graphs show the property reports for a HINT simulation with both age and accessibility properties in which transmission is lower for hard-to-access individuals and there are an equal number of “easy” and “hard” to access individuals. The first graph shows the effect of targeting vaccination to children aged 6 to 10. The second graph shows the effect of instead targeting it to all individuals who are easy to access.

To run this example simulation, see the Generic/HINT_AgeAndAccess scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information.

_images/HINT_AgeAndAccess_PropertyReport_agetargeted.png

Figure 1: Age-targeted vaccination

In this example, the outbreak begins in the easily accessible population and vaccination is targeted to children aged 6 to 10. Notice the dramatic decrease of the infection in 6 to 10 year olds due to the vaccination of this group. Compare infections in other ages, noting the overall decrease in infection across age groups even though only 6 to 10 year olds were vaccinated.

_images/HINT_AgeAndAccess_PropertyReport_accesstargeted.png

Figure 2: Access-targeted vaccination

In this example, the outbreak begins in the inaccessible population and vaccination is targeted to all individuals who are easily accessed. Notice how the infection is almost entirely eliminated among the easily accessible population, but there is only a slight reduction in infection among the inaccessible population that was not reached by the vaccination campaign.

Vaccination and herd immunity

In a basic compartmental model, we often assume all individuals are susceptible before the importation of an outbreak. However, vaccination is one of the most effective ways to prevent or contain a disease outbreak.

Starting from the traditional SIR equation:

\[\begin{split}\begin{aligned} \frac{dS}{dt} & = -\frac{\beta SI}{N}\\ \frac{dI}{dt} & = \frac{\beta SI}{N} - \gamma I\\ \frac{dR}{dt} & = \gamma I \end{aligned}\end{split}\]

For an outbreak to start, the following condition needs to be satisfied:

\[\frac{dI}{dt} = \frac{\beta SI}{N} - \gamma I > 0\]

If a vaccination campaign with coverage p \(\in\) [0, 1] is performed before the outbreak, a fraction of susceptible people move to the recovered compartment. If the vaccine take is e \(\in\) [0, 1], representing the probability of being protected after receiving a vaccine dose, the fraction of immune people due to vaccination is ep. Therefore, the previous condition can be reduced to:

\[\begin{split}\begin{aligned} \left(\beta (1 - e p) - \gamma\right) I & > 0\\ R_0 (1 - e p) & > 1\\ R_{eff} & > 1 \end{aligned}\end{split}\]

Reff is also called the effective reproductive number. Vaccination can reduce the disease’s ability to spread, and the outbreak can be prevented or stopped with less than 100% coverage. When Reff= 1, there exists a minimum vaccination coverage that can prevent a disease outbreak. This minimum coverage required to prevent an outbreak is usually called herd immunity (represented as Pherd). Therefore, the analytical form of Pherd can be derived based on the previous condition:

\[P_{herd} = \frac{1}{e}\left(1-\frac{1}{R_0}\right)\]
Multiple rounds of vaccinations

If multiple vaccine interventions are performed in the same area, people are selected on a binomial basis and all individuals have the same probability of being included. If the vaccine coverage is p, every individual has a probability p of being selected in a given round. After the first round, the fraction of non-vaccinated is 1-p, and after n rounds this fraction is (1 - p)n. Therefore, the fraction of people getting at least 1 dose is:

\[1-(1-p)^n\]

For example, the fraction of people getting at least one vaccination with a 50% campaign coverage is shown in the following table. After a few rounds, the coverage increases significantly with the number of campaigns.

Number of campaigns

Covered percentage (>=1 dose)

1

50%

2

75%

3

87.5%

4

93.75%

5

96.875%

For an example simulation, see the Generic/Vaccinations scenario in the downloadable EMOD scenarios zip file. Review the README files there for more information.

The following graphs show a baseline SIR outbreak and then the effect of a vaccination campaign distributed to the entire population. The vaccination campaign is repeated three times, seven days apart. The vaccine has 100% take and 50% demographic coverage. With this configuration, the fraction of immune people is above herd immunity and the outbreak does not spread.

_images/Vaccination_InsetChart_baseline.png

Figure 1: Baseline SIR outbreak

_images/Vaccination_InsetChart_broad.png

Figure 2: Broad vaccination campaign achieving herd immunity

However, this is usually not the case. In recent polio eradication campaigns, the number of supplemental immunization activity (SIA) campaigns planned in certain high-risk districts is greater than 6 per year, but poliovirus still persists in the area due to certain groups that are chronically missed. This can be caused by low accessibility, exclusion from SIA microplans, or vaccine refusal. Reff has not been driven below 1 because these susceptible people in the chronically missed groups are still in contact with the rest of population. In some modeling simulations, this assumption has to be included.

In this second example, the same 50% campaign coverage is repeated so that the same amount of vaccine is used. However, 30% of the population is not accessible to any vaccine campaigns. Although the number of vaccine doses used is the same as the previous example, the overall coverage is much lower. Creating campaigns that target interventions is described in more detail in Targeting interventions to nodes or individuals.

Number of campaigns

Covered percentage of total population

Covered percentage of groups with access

Covered percentage of groups without access

1

50%

71.43%

0%

2

59%

91.84%

0%

3

68.37%

97.67%

0%

4

69.53%

99.33%

0%

5

69.87%

99.81%

0%

The following graph shows the same SIR outbreak when 30% of the population is chronically missed by the vaccination campaign, allowing the outbreak to persist.

_images/Vaccination_InsetChart_access.png

Figure 3: Vaccination campaign that misses 30% of the population

Cascade of care

Some diseases, such as HIV, have a complex sequential cascade of care that individuals must navigate. For example, going from testing to diagnosis, receiving medical counseling, taking antiretroviral therapy, and achieving viral suppression. Other life events, such as pregnancy, migration, relationship changes, or diagnostic criteria may trigger different medical interventions.

Health care in EMOD can be applied to individuals, such as through a vaccination campaign, or be sought out by various triggering events including birth, pregnancy, or symptoms. A potential problem created by this structure is that an individual could end up in care multiple times. For example, an individual might have an antenatal care (ANC) visit and, in the same time step, seek health care for AIDS symptoms, both leading to HIV testing and staging.

To avoid this situation, you can configure interventions using the InterventionStatus individual property in the demographics file (see NodeProperties and IndividualProperties for more information). In the demographics file, create as many property values as necessary to describe the care cascade. For example, undiagnosed, positive diagnosis, on therapy, lost to care, etc.

In the campaign file, set up your event coordinator as you typically would, using Target_Demographic, Property_Restrictions_Within_Node, and other available parameters to target the desired individuals. See Targeting interventions to nodes or individuals for more information on targeting interventions and Events and event coordinators for all available event coordinators.

Then, in the intervention itself, you can add any properties that should prevent someone who would otherwise qualify for the intervention from receiving it. For example, someone who has already received a positive diagnosis would be prevented from receiving a diagnostic test if they sought out medical care for symptoms. You can also add the new property that should be assigned to the individual if they receive the intervention.

The following example shows a simplified example with two interventions, a diagnostic event and distribution of medication. The demographics file defines intervention status values for having tested positive and for being on medication.

{
    "Use_Defaults": 1,
    "Events": [{
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "class": "SimpleDiagnostic",
                    "Disqualifying_Properties": [
                        "InterventionStatus:OnMeds"
                    ],
                    "New_Property_Value": "InterventionStatus:TestPositive",
                    "Base_Sensitivity": 1.0,
                    "Base_Specificity": 1.0,
                    "Cost_To_Consumer": 0,
                    "Days_To_Diagnosis": 5.0,
                    "Dont_Allow_Duplicates": 0,
                    "Event_Or_Config": "Event",
                    "Positive_Diagnosis_Event": "NewInfectionEvent",
                    "Intervention_Name": "Diagnostic_Sample",
                    "Treatment_Fraction": 1.0
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": [
                        "NewInfectionEvent"
                    ],
                    "Disqualifying_Properties": [
                        "InterventionStatus:OnMeds"
                    ],
                    "New_Property_Value": "InterventionStatus:OnMeds",
                    "Demographic_Coverage": 1.0,
                    "Actual_IndividualIntervention_Config": {
                        "class": "ARTBasic",
                        "Viral_Suppression": 1,
                        "Days_To_Achieve_Viral_Suppression": 1000000
                    }
                }
            }
        }
    ]
}
Cascade of care for the HIV model

While health care systems, with individuals entering and leaving care, can be configured in all EMOD sim types, the HIV model makes particular use of this feature. Living with HIV requires a series of health actions that enable individuals to reach and continue care; these actions also impact the partners of HIV+ individuals.

Generally, the HIV cascade of care begins with a positive diagnostic test and linkage to ART. In practice, the cascade is more complicated. There are multiple routes to initiate diagnostic testing, and individuals may not always be eligible to enroll on ART. Further, once a patient begins ART, there is no guarantee that they will remain on ART. In some cases, patients do not return for their test results, or are otherwise lost to follow-up (LTFU). The figure below depicts the potential routes for the HIV cascade of care.

_images/cascade_of_care.jpg

Cartoon depicting the cascade of care for HIV patients. Reprinted from Klein et al 2014.

Entry into the cascade: types of testing

The cascade of care is, in its simplest form, a series of interventions that are distributed to individuals based on properties that individual was assigned, either by configuration in the demographics file, or by assignment of the model as they were born into the simulation population. Therefore, entry into the cascade is simply a matter of possessing the appropriate properties as required by the particular intervention.

However, when creating a health care system for HIV, entry into care routes is accomplished through testing. As individuals receive diagnostic tests, their results will enable them to enter into the care system. There are several types of tests that can be implemented:

  • Voluntary counseling and testing. Individuals that have reached (or passed) the age of sexual debut are eligible to receive regular testing. These individuals can get tested at a configurable rate which can vary by calendar year. Unlike other forms of testing, voluntary can only result in one positive result; after which, individuals are linked to care (although they may fail to link or drop out).

  • Antenatal testing. Pregnant women can receive testing, typically at 12 or 14 weeks gestation. These rates are also configurable, and can vary by calendar year.

  • Infant testing. Infants born to HIV+ mothers have a probability of being tested (typically at 6 weeks of age). The probability is configurable, and can change over time.

  • Symptomatic testing. Individuals can get tested when they become symptomatic, which is predicted based on CD4 count. The probability of seeking testing when symptomatic is configurable, but is typically set to 100%. However, symptoms may present at different CD4 counts for different individuals; gender-based percentages for symptom presentation are configurable.

It is possible to create different triggers for testing, by using the IndividualProperties in the demographics file (see Demographics parameters for more information). The Property, Value, and Initial_Distribution parameters can be used to tag individuals in as detailed a manner as needed, and interventions (such as diagnostic tests) can be configured to use those tags for the target of the intervention. EMOD keeps track of age, pregnancies, births, and other time-sensitive events, and updates those properties as needed.

Moving through the cascade

Individuals enter the cascade when one of their properties is targeted by a diagnostic test, for example, by reaching the age of sexual debut, showing HIV symptoms, or by having a “high risk” label. Next, the model will use the positive test to activate the next step in care, such as an intervention configured to link the individual to ART or to initiate a follow-up test. Accuracy in test results is not perfect, so there is a probability of receiving a false negative test result for some individuals, and they will not enter the care system. Those entering care typically schedule a follow-up appointment to receive a CD4 count result and to determine their disease stage and ART eligibility. Not all individuals will return for this round of testing and will subsequently be lost to follow-up (LTFU). All LTFU individuals will not return through the volunteer testing route. CD4 count test results determine if the individual is eligible to begin ART or should link to pre-ART if ineligible. The probability of linking to pre-ART can be configured to increase over time (such that it matches historical trends). Pre-ART treatment consists of monitoring visits that are scheduled to occur regularly (e.g. every 6 months), and the probability of returning for consecutive visits can be configured. Individuals can become eligible for ART during these visits. For individuals on ART, rates for dropout can be configured (and may also change over duration on ART).

To summarize, the cascade of care system consists of a series of campaign intervention classes which are configured to have dependencies based on the previous intervention (or it’s outcome). The simplified version is as follows:

  1. Start with diagnostic testing.

  2. If positive, enroll in follow-up testing.

  3. HIV+ individuals link to either pre-ART or ART.

  4. If pre-ART, individuals return periodically for monitoring; may eventually link to ART.

Care systems will likely be much more complicated: there are many “leaky” points in the cascade, where individuals can drop out of care or are LTFU. Further, care systems can be created to specifically mirror current care systems, and so may differ in the types and numbers of diagnostics used, the probability that individuals will return or drop out of care, and the treatment guidelines that will trigger entry into the care system itself. Note that treatment guidelines can change over time in order to match the history of past guidelines (see Health care systems for more information).

Configuring the cascade

Configuring a cascade of care system can be complicated, as it is akin to creating a large network with many dependent properties. However, it can be simplified by breaking the process down into its component steps.

First, in the demographics file, use the IndividualProperties parameters (Demographics parameters) to appropriately “tag” individuals to make them eligible (or ineligible) for treatment. For example, the Property, Values, and Initial_Distribution parameters can be configured to partition the population into those who will be accessible for treatment versus those who will not be accessible. Further, additional properties can be added, such as InterventionStatus, where the Values array contains a list of statuses which may act to trigger an event that will cause an intervention to be distributed, or disqualify the individual from a particular type of care (the proportion of individuals starting out in each category is listed in the Initial_Distribution array). The InterventionStatus IndividualProperty can be used to keep track of where individuals are within the cascade, and to help prevent them from being in more than one arm of the cascade at a time.

The following example shows a population with 80% individuals accessible to health care, and all individuals starting out without any intervention labels (e.g., at the start of the simulation, no one is in a category for health care).

{
    "IndividualProperties": [{
            "alpha__Comment": "80% Healthcare Accessible",
            "Property": "Accessibility",
            "Values": ["Yes", "No"],
            "Initial_Distribution": [0.8, 0.2]
        },
        {
            "Property": "InterventionStatus",
            "Values": [
                "None",
                "ARTStaging",
                "ARTStagingDiagnosticTest",
                "LinkingToART",
                "LinkingToPreART",
                "OnART",
                "OnPreART",
                "HCTTestingLoop",
                "HCTUptakeAtDebut",
                "HCTUptakePostDebut",
                "TestingOnANC",
                "TestingOnChild6w",
                "TestingOnSymptomatic",
                "LostForever"
            ],
            "Initial_Distribution": [
                1,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0,
                0
            ]
        }
    ]
}

After setting up the population, it is time to configure the health care cascade itself. This is done in the campaign file, using a series of different campaign interventions and event coordinators to determine which interventions (such as diagnostic tests, or treatment regimes) will be utilized, who will be targeted for the interventions, and when (or how) the interventions will be triggered.

As described in Campaign file, distributing an intervention (for example a diagnostic test), it is necessary to configure a campaign event, an event coordinator, and the actual intervention itself. So to configure a care cascade, start with the most basic route for care, such as a diagnostic test given to individuals that have reached the age of sexual debut, and build up the conditions. You will need to determine:

  • What will trigger the intervention (in this example, reaching the age of sexual debut)

  • What properties will disqualify individuals from receiving the intervention

  • What the actual intervention will be (here, a diagnostic test)

  • What will occur as a result of the intervention (here, what happens due to positive or negative test results)

  • What new value (i.e., tag) to assign individuals that have received the intervention

{
    "class": "CampaignEvent",
    "Event_Name": "HCTUptakeAtDebut: state 0 (decision, sigmoid by year and sex)",
    "Start_Day": 0,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "class": "NodeLevelHealthTriggeredIV",
            "Trigger_Condition_List": [
                "STIDebut"
            ],
            "Property_Restrictions_Within_Node": [{
                "Accessibility": "Yes"
            }],
            "Actual_IndividualIntervention_Config": {
                "class": "HIVSigmoidByYearAndSexDiagnostic",
                "Disqualifying_Properties": [
                    "InterventionStatus:OnART",
                    "InterventionStatus:LinkingToART",
                    "InterventionStatus:OnPreART",
                    "InterventionStatus:LinkingToPreART",
                    "InterventionStatus:ARTStaging"
                ],
                "New_Property_Value": "InterventionStatus:HCTUptakeAtDebut",
                "Days_To_Diagnosis": 0,
                "Ramp_Min": -0.0052,
                "Ramp_Max": 0.25,
                "Ramp_MidYear": 2000,
                "Ramp_Rate": 1,
                "Female_Multiplier": 1.3,
                "Positive_Diagnosis_Event": "HCTTestingLoop0",
                "Negative_Diagnosis_Event": "HCTUptakePostDebut0"
            }
        }
    }
}

The above example of syntax demonstrates a potential first step in a care cascade. Note that the intervention NodeLevelHealthTriggeredIV is used to target all individuals in the node that have the property “Accessibility” : “Yes”. If we were using the example from the demographics file shown above, this would target 80% of our population. Then, those targeted individuals are further broken down into those that have reached the age of sexual debut, using the Trigger_Condition_List value of “STIDebut”. The individuals meeting that criteria are given the intervention HIVSigmoidByYearAndSexDiagnostic, which is a diagnostic test that allows for the probability of a positive diagnosis to be configured sigmoidally in time. Individuals are excluded from this intervention if they are on ART, on PreART, are linking to ART or PreART, or are undergoing ARTStaging (as described in the Disqualifying_Properties). The New_Property_Value parameter will reassign the individuals receiving this intervention a new InterventionStatus, and the parameters Positive_Diagnosis_Event and Negative_Diagnosis_Event will determine the next step in the cascade care system for individuals receiving a positive or negative test result.

Expanding the care system is an iterative process; build upon the events by adding tests or treatment programs that will look for individuals that go through the prior steps. Some steps may not be directly linked to the prior interventions, such as testing for infants or pregnant women; these can be added in as new entry points to the care system. The below syntax example builds upon the above example, by using the Negative_Diagnosis_Event value of “HCTUptakePostDebut0” to trigger the next step in the care, and then progressively builds the next several steps.

{
  "Events": [
    {
      "class": "CampaignEventByYear",
      "Event_Name": "HCTUptakePostDebut: state 0 (Post-Debut)",
      "Start_Year": 1990,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "HCTUptakePostDebut0"
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "STIIsPostDebut",
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "HCTUptakePostDebut1"
          }
        }
      }
    },
    {
      "class": "CampaignEventByYear",
      "Event_Name": "HCTUptakePostDebut1: state 1 (1-year delay, reachable)",
      "Start_Year": 1990,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "HCTUptakePostDebut1"
          ],
          "Property_Restrictions_Within_Node": [
            {
              "Accessibility": "Yes"
            }
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "HIVMuxer",
            "Muxer_Name": "HCTUptakePostDebut",
            "Max_Entries": 1,
            "Disqualifying_Properties": [
              "InterventionStatus:LostForever",
              "InterventionStatus:OnART",
              "InterventionStatus:LinkingToART",
              "InterventionStatus:OnPreART",
              "InterventionStatus:LinkingToPreART",
              "InterventionStatus:ARTStaging",
              "InterventionStatus:HCTTestingLoop"
            ],
            "New_Property_Value": "InterventionStatus:HCTUptakePostDebut",
            "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
            "Delay_Period_Exponential": 365,
            "Broadcast_Event": "HCTUptakePostDebut2"
          }
        }
      }
    },
    {
      "class": "CampaignEventByYear",
      "Event_Name": "HCTUptakePostDebut: state 2 (Decision to uptake HCT)",
      "Start_Year": 1990,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "HCTUptakePostDebut2"
          ],
          "Property_Restrictions_Within_Node": [
            {
              "Accessibility": "Yes"
            }
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "HIVSigmoidByYearAndSexDiagnostic",
            "Disqualifying_Properties": [
              "InterventionStatus:LostForever",
              "InterventionStatus:OnART",
              "InterventionStatus:LinkingToART",
              "InterventionStatus:OnPreART",
              "InterventionStatus:LinkingToPreART",
              "InterventionStatus:ARTStaging",
              "InterventionStatus:HCTTestingLoop"
            ],
            "New_Property_Value": "InterventionStatus:HCTUptakePostDebut",
            "Days_To_Diagnosis": 0,
            "Default_Value": 0,
            "Ramp_Min": -0.01,
            "Ramp_Max": 0.6,
            "Ramp_MidYear": 2007,
            "Ramp_Rate": 1,
            "Female_Multiplier": 1,
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "HCTTestingLoop0",
            "Negative_Diagnosis_Event": "HCTUptakePostDebut1"
          }
        }
      }
    }
  ]
}

The example can be illustrated with a flow chart:

_images/hiv-cascade-example.png

The individual enters the cascade after reaching the age of sexual debut (STIDebut on the chart). They received a diagnostic test, and positive results routed them into the the HCTUptakePostDebut0 intervention (another diagnostic test); a positive result routes the individual into the next intervention, and the cascade continues. Note that this example has been simplified, and does not include individuals that are lost to follow up, or any ART interventions.

STI model overview

The EMOD STI model is an agent-based stochastic simulator of sexual and vertical disease transmission. The model utilizes microsolvers to combine detailed information on contact networks, pair formation, and human population dynamics. EMOD can be calibrated to particular geographic locations, and the microsolver framework enables the model’s functionality to be highly modifiable. To use the STI model, set the configuration parameter Simulation_Type to STI_SIM.

The STI transmission mode framework enables person-to-person transmission through a network of relationships or contact networks, each of which has a specific transmitter and recipient of every transmission event. To organize the networks, individuals form one or more relationships that are remembered over time.

Preference for partners is configurable through the model’s input files. Inside the model, the “supply and demand” for types of partners is balanced by a pair formation algorithm (PFA) that, if desired, can dynamically adjust the rates of relationship formation in each demographic category to produce a constant mixing pattern, even with demographic changes in the population. Alternatively, the dynamic adjustments can be turned off to allow mixing patterns to change in response to demographic changes. For more information on the PFA, see Relationships and contact networks.

The contact networks formed within the STI model are driven by the behavioral parameters found in the Society section of the demographics file. These parameters control pair formation, relationship types, and level of relationship concurrency. For more information about this section of the demographics file, see Society.

Because the STI model is built around person-to-person contact networks, human relationships impact nearly every aspect of model functionality. For example, migration is supported in the STI model, but is more complicated than in other disease types, as now it impacts the relationships experienced by the migrating individual (see Relationships and contact networks for more information).

The following pages describe the structure of the STI model and explore the model components. Additionally, the specifics of the HIV model, which is based on the STI model, are discussed in detail in the articles Bershteyn, Klein, Wenger, and Eckhoff, arXiv.org, and Klein, Bershteyn, and Eckhoff, AIDS 2014.

Relationships and contact networks

Human relationships are at the center of the EMOD STI model. Who individuals form sexual relationships with, and how those partnerships are formed, are the basis for STI transmission. The EMOD STI model contains detailed information for configuring the relationships and tracking partnerships over time. There is a pair formation algorithm (PFA) that balances the “supply and demand” for partners (see Pair formation algorithm (PFA) for more information), and numerous parameters that configure the type and duration of relationships, as well as the ages and behavior of the participants. These relationship settings are configured in the demographics file; for a complete list of the parameters see Demographics parameters; the majority of the relationship parameters will be located in the Society section.

Relationship formation

The following section will describe how EMOD determines eligibility for relationship status, and how relationships then form and proceed among eligible individuals. As a stochastic, agent-based model, EMOD can track individuals and create dynamic relationship networks. The STI model has included an algorithm to form sexual relationships with a specific joint age-mixing distribution, and enables control over the rates at which individuals seek new relationships.

For more information on relationship formation, including the math for the pair formation algorithm, see Klein 2012 and Bershteyn et al 2013.

Pair formation algorithm (PFA)

Individuals seeking to enter a relationship are managed by a feed-forward pair formation algorithm (PFA). This algorithm has been described by Bershteyn et al 2012. The PFA dynamically adjusts the rates of relationship formation as the population structure changes; feed-forward can be disabled during the simulation to allow future patterns of relationship formation to change in response to demographic shifts in the population. The algorithms used for each type of relationship (see Relationship types and durations for more information) are identical, but utilize different input data about the age distribution and age gaps within partnerships. Entrance into the PFA is governed by the relationship flow (see Relationship flow for more information).

Internally, the algorithm maintains a series of queues that are arranged by age and gender. Discrete age bins, N in total, are generated in a manner that is consistent with the discretization of the input mixing matrix. The input matrix is set up such that the entry at position (i, j) is the probability of a male of age bin i pairing with a female of age bin j. When a male of age m enters into the algorithm, a desired female age f* is sampled from the conditional probability,

f* ~ p(F|M = m)

_images/PFA.png

The pair formation algorithm used to form relationships between individuals who seek them.

Individuals entering the PFA are immediately placed into a gender-specific queue, with males entering into queues seeking females of a desired age and females are placed in separate queues for specific age bins. If a female happens to be waiting in the corresponding age bin within the algorithm, a relationship is formed and the two individuals leave the algorithm. Otherwise, the male will continue to wait in the queue. When a female enters into the algorithm, she proceeds directly to the (female) age bin corresponding to her age. If a male is already waiting for a female of her age bin, a pair is formed; otherwise she will continue to wait in the queue.

_images/hiv-queues.png

Illustration of males and females forming queues.

The queues fill over a period of time corresponding to the relationship type. After the filling period (the length of which is dependent on the relationship type), a processing step forms relationships by working linearly through the male queue. A female partner is selected for the male at the head of the queue based on age and availability. Note that for relationships with a low probability of formation, the algorithm may have difficulty finding suitable partners, as availability may be low. For example, the input data may be configured such that there is a 1% chance that a 20 year old male will have a relationship with a 60 year old female. If the 20 year old male only has 60 year olds to choose from (because younger women are not looking for new relationships), then there will be a skew from the desired rates due to this lack of supply. The parameter PFA_Cum_Prob_Selection_Threshold can be used to reduce this issue.

Specifically, a male of age m samples a partner age, f, from

p(F = f) proportional to

p(F = f|M = m) if Nf > 0 0 otherwise.

Here, Nf is the number of females queued in age bin f and p(F = f|M = m) is the conditional distribution derived from the input matrix. If p(F = f) is identically zero, the male remains in the queue for the next processing round. Otherwise, the female of the sampled age bin who has been waiting the longest is selected as the partner. The paired individuals are removed from their respective queues, and the process is repeated. Note that this algorithm is symmetric: in principle, either males or females could choose based on their respective marginal distributions.

Note that age bins and other PFA parameters are configured in the demographics file; see the Pair_Formation_Parameters in Demographics parameters.

Age of sexual debut

Individuals are eligible to enter relationships only after reaching the age of sexual debut. The age of sexual debut is randomly drawn for each individual from a Weibull distribution. Weibull distributions are used often in EMOD and require two parameters: a shape parameter and a scale parameter.

The shape parameter governs the shape of the density function. When the shape parameter is equal to 1, it is an exponential distribution. For shape parameters above 1, it forms a unimodal (hump- shaped) density function. As the shape parameter becomes large, the function forms a sharp peak. The inverse of the shape parameter is sometimes referred to here as the “heterogeneity” of the distribution (heterogeneity = 1/shape), because it can be helpful to think about the degree of heterogeneity of draws from the distribution, especially for hump-shaped functions with heterogeneity values between 0 and 1 (i.e., shape parameters greater than 1).

The scale parameter shifts the distribution from left to right. When heterogeneity is small (i.e., the shape parameter is large), the scale parameter sets the location of the sharp peak. The scale parameter is related to the median of the distribution by the equation:

Median = Scale × (ln(2))1/Shape = Scale × (ln(2))^Heterogeneity

so that when heterogeneity is close to zero, the median is close to the scale parameter.

To define the distribution of age of sexual debut, three parameters are specified: the Weibull heterogeneity parameter, the Weibull scale parameter, and the minimum possible age of sexual debut. The first two parameters can be set to different values for males and females. The third parameter prevents debut ages lower than a specific value, even if the Weibull distribution has some mass below that value. These parameters are located in the config.json input file; for more information on Weibull parameters, see Weibull distributions.

There is typically a lag between eligibility and the first relationship, and that can be due to how partner choice is made. The input matrix enables individuals to preferentially select partner age, and can be configured for each relationship type. To configure age preferences, the matrix will be created in the Pair_Formation_Parameters in Demographics parameters using the Joint_Probabilities parameter.

_images/relationships-debut.png

The lag between age of eligibility for relationship formation and age at actual relationship formation. The green line shows the expected distribution of individuals at sexual debut, the red line shows the number of individuals that have reached sexual debut, and the blue line shows the actual age at relationship formation.

Relationship flow

For all individuals in the model, he or she may participate in multiple relationships, some of which may occur concurrently. However, the “relationship flow” specifically refers to the processes of breaking apart existing relationships and driving the formation of new relationships. In other words, the processes that move individuals through the PFA.

In order for the PFA to produce relationships according to the input matrix, equal numbers of males and females must enter the algorithm and their age distributions must match the respective marginals of the input matrix. To ensure that this occurs, a feed-forward control is used in which the rates at which individuals in each age bin and gender enter for each relationship type are adjusted daily. The input matrix dictates only the relative number of relationships formed between pairs of different ages, but not the absolute number of relationships formed by the PFA. This total throughput of relationships formed is set such that the expected number of individuals seeking a relationship of a particular type, after rate adjustment to meet the input matrix, matches the number of males and females that would have sought that relationship had the rates not been adjusted for the input matrix. Thus, the rate adjustment changes the age distributions of the individuals seeking relationships, but not the total number of each type of relationship formed.

This adaptive daily rate control allows the model to automatically discover the rates of relationship entry that are consistent with the input matrix. It is conceivable, however, that events causing large demographic shifts might change the input matrix. For example, when comparing simulations with universal HIV treatment versus no treatment, it is conceivable that demographic influence of the disparate AIDS death tolls should cause the input matrices to diverge. Therefore, adaptive rate control may be disabled after an initial burn-in period, after which the entrance rates will remain fixed at their final controlled values and the input matrix is permitted to change as the simulation progresses.

Relationship types and durations

Partnerships form after individuals have reached the age of sexual debut, and partners are chosen from a pool of available individuals within the desired age group (see Pair formation algorithm (PFA) for more information). However, partnerships are also categorized by type, which will impact a variety of factors governing relationship duration and the behavior of the participants.

Currently, EMOD supports four different types of heterosexual relationships: transitory, informal, marital, and commercial. Each type can have independently configured mixing patterns, rates of formation, and average durations. In addition, each type of relationship can configure specific condom usage probabilities, rates of coital acts, and migration actions. Individuals can be involved in multiple relationships of different types (see Concurrent partnerships for more information about multiple partnerships).

While relationship types are fully configurable, it is useful to use guidelines when doing so. Transitory relationships are typically short and involve younger participants; informal relationships tend to describe longer, non-marital relationships with participants of intermediate age; marital relationships are long term with older participants; and commercial relationships are those involving transactional relationships with commercial sex workers. Each relationship duration is governed by a Weibull distribution, which determines the duration that is assigned to a relationship upon formation. The duration time is then used to calculate the scheduled end time of the relationship. In some cases, relationships will dissolve prior to the scheduled end time, such as when a participant dies. Start times, scheduled end times, and actual end times for each relationship are recorded in output files (see Output files (reports) for more information on output).

_images/relationships-types.png

An example of potential relationship durations by type (here, transitory, informal, and marital).

Coital frequency and coital dilution

For sexually transmitted infections, each coital act represents a potential transmission event. Because of this, it is possible to configure the frequency of coital acts independently for each relationship type. Individual coital acts are simulated for disease-discordant relationships only. When an individual becomes infected, the discordancy states of all relationships involving the individual are updated. The timing of coital acts is random, such that the time until the next coital act is exponentially distributed with the configured rate. When multiple coital acts occur in the same timestep, as determined by a draw from a Poisson distribution, they are accounted for using Bernoulli statistics with the associated transmission probability for each of the individual coital acts.

When an individual participates in multiple partnerships simultaneously, the model can incorporate coital dilution, i.e., a change in the frequency of coital acts as a result of having multiple partnerships. The reduction in coital dilution is independently configurable for individuals with two, three, or more than three partners. When the two participants in a relationship have different numbers of partners, then the reduction factor from the person with more partners is applied.

_images/coital-acts.png

The number of relationships consummated between different partners. Relationships in which both participants have one partner (red) have more coital acts than those in which one or both participants have multiple relationships (blue).

Condom usage

Each relationship type has numerous relationship-specific properties, as discussed above. Condom usage probabilities can be configured for each type; while the rate is set at the start of the relationship, the probability of usage over time follows a sigmoidal curve which accounts for lower usage rates in longer-term relationships. The condom usage probability, P(t) depends on the simulation time t as follows:

P(t) = h / [1 + e ^(-R(t-t0))] +l

Where l, h, t0, and r are configurable for the parameter Condom_Usage_Probability (they correspond to min, max, mid, and rate, respectively. See Demographics parameters for more information).

Concurrent partnerships

EMOD can be configured to allow for individuals to participate in multiple relationships simultaneously. Concurrency is controlled by “flags” that determine if an individual is eligible to seek additional relationships when already participating in a relationship of that type. Flags are configured using both Concurrency_Parameters and Concurrency_Configuration parameters in the demographics file. For each relationship type, it is possible to configure the probability of extra relationships and the maximum number of extra relationships for both males and females.

Enabling concurrency increases the average number of simultaneous partners, and over the course of the simulation, also increases the average number of lifetime partners. However, despite the increase in concurrency and number of lifetime partners, the overall size of the connected component of the network may remain similar. Numerous factors influence network connectivity, including population size, population structure, and the configured formation rates, durations, and mixing patterns for each relationship type. This mix of factors determines the extent to which “serial monogamy” is sufficient to connect the network.

Although the configuration parameters allow high levels of concurrency, the actual levels of concurrency at any given time are likely going to be considerably lower. That is because the extra- relational flags only create the potential for individuals to add relationships, but depending on the formation rate and mixing pattern, actual formation may not occur. This is similar to the way that sexual debut occurs earlier than actual formation of the first relationship. However, it is possible to control the proportion of “potential concurrency” that is realized by modifying the rate ratios of concurrent relationship formation for those with the appropriate flag. It should be noted as well that the formation of a marital partnership, which has the lowest probability of permitting concurrency and the longest duration, frequently prevents individuals from taking on additional partnerships. Combined with the increased rates of entry into shorter transitory and informal partnerships, this leads to increased concurrency earlier in life and declining concurrency later in life, although there is no explicit age-dependence of concurrency in the model.

Concurrency may be configured independently across each relationship type, or may be correlated. When concurrency is distributed independently by relationship type, few individuals will reach high levels of concurrency; however, it is possible to concentrate risk in a subset of the population by using correlated concurrency. These settings can be found in the Concurrency_Configuration section of the Demographics parameters.

Time-course

The time-course of a simulation run is depicted graphically below. In general, simulations begin prior to the start of infection, (in the example, the year 1960) to allow ample time for relationships to “burn-in.” During this burn-in time, individuals with demographic properties dictated in the demographics file begin forming relationships; relationship formation rates for each gender and relationship type are updated daily using the relationship flow algorithm (see Relationship flow for more information). Adjustment of pair formation entry rates is terminated at a specific timepoint (in the example, at 1975) and the rates are fixed at that value for the remainder of the simulation.

Next, a timepoint is selected to see infections (1980 in the example). The seeding process infects a configured percentage of the population, as determined by data and configured in a campaign file (see Outbreak for more information).

The last portion to configure is the introduction of treatment. Here, the ART intervention is enabled in the year 2012. Eligible individuals enroll in ART as determined in the campaign file. ART distribution continues for the duration specified, which here is the remainder of the simulation which runs until 2050.

_images/time-course.png

An example time-course of an EMOD simulation, originally published in Bershteyn et al. 2012, arXiv.

Transmission

In the EMOD STI model, disease transmission can occur via two routes: sexual transmission or vertical transmission (e.g. mother-to-child). The probability of transmission is calculated for each discordant coital act and each childbirth.

Unlike the relationship parameters (see Relationships and contact networks), parameters that govern transmission are found in the configuration file (see Configuration parameters for a complete list of configuration parameters). Parameters used to interrupt transmission will be found in the campaign file (see Campaign parameters for a complete list of campaign events and their parameters).

Sexual transmission

Sexual transmission occurs between disease-discordant individuals that are paired in a relationship. Transmission occurs via coital acts, so the probability of transmission will vary by relationship type (see Relationships and contact networks for information on relationship type, formation, and coital frequencies). In addition, there are numerous configurable factors that can influence the transmission rate.

Base infectivity and its multipliers

Sexual transmission is configured through a base rate of infectivity, which is the transmission rate per total coital acts. See Infectivity and transmission parameters for more information. This base rate can be modified through various multipliers and scalars, such that transmission rates can vary by:

  • Age and gender. The rate of male-to-female heterosexual transmission can be configured to be different than the rate of female-to-male heterosexual transmission. This gender bias in transmission can also be varied according to the age of the female partner. Both the gender and age multipliers on transmission are configured through a pair of matched arrays in the config.json file (Male_to_Female_Relative_Infectivity_Ages and Male_to_Female_Relative_Infectivity_Multipliers). Note that the lengths of both arrays must be equal, so each multiplier has a corresponding age. To remove age dependence, put just one value in each array. When multiple values are provided, the multiplier on the probability of transmission is linearly interpolated between the specified ages. Ages do not have to be integer values, and ages younger than the youngest specified age are assigned the value for the youngest specified age. Likewise, ages older than the oldest specified age are assigned the value for the oldest specified age.

  • Individuals. The transmission rate can also be configured to be heterogeneous among individuals, with a multiplier on infectiousness sampled from a log normal scale. The multiplier is assigned to each individual at birth, and will be applied to every infection in that individual’s lifetime.

  • STI co-infection. While the EMOD STI model does not support simultaneous transmission of more than one sexually transmitted infection, it does support the inclusion of non-transmitting co-infections that increase infectiousness and susceptibility for the transmission of the primary disease being modeled. Co-infection multipliers are set in the configuration file, while seeding or clearing co-infections is accomplished by using campaign interventions.

  • Condom usage. Unlike the above multipliers, condom usage configures a blocking effect on transmission, such that the parameter represents the proportion of reduction in transmission. Each relationship type can have an independent probability of condom usage, which changes over time (recall that relationship types are configured in the demographics file; see Relationships and contact networks for more information). The transmission blocking properties of condoms are then set in the config.json file. This blocking probability will be applied to condom use across all relationship types. Finally, it should be noted that condoms may also be distributed through a campaign intervention. For more information, see STIBarrier.

Note that in addition to configuration parameters, there are campaign interventions that will also impact the transmission rate. For example, voluntary male medical circumcision, the use of vaccines, and the use of treatments, can be distributed to individuals to lower the transmission rate. For more information, see Individual-level interventions.

Vertical (mother-to-child)

The EMOD STI model supports vertical transmission of STIs via mother-to-child transmission (MTCT). The model links the STI status of specific mothers with exposure to specific children, and does this through the simulation of individual pregnancies. While overall fertility rates and birth rates are configured in the demographics file, the transmission parameters governing MTCT are configured in the configuration file.

To implement MTCT, maternal transmission must be enabled. This will allow infectious mothers to transmit to their children. Additionally, there are parameters that can modify the transmission probability. Finally, in order to simulate individual pregnancies, the Birth_Rate_Dependence parameter must be set to INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR. For more information on these parameters, see Population dynamics.

Note that there is a campaign intervention that can be configured to disrupt MTCT, the prevention of mother-to-child transmission (PMTCT) intervention. For more information, see PMTCT.

HIV model overview

The EMOD HIV model is an agent-based stochastic simulator of sexual and vertical HIV transmission. It is used to simulate HIV conditions for national-level epidemics in order to evaluate the cost and impact of various treatment and control programs. The model utilizes microsolvers to combine detailed information on human immunity, within-host viral dynamics, the effects of antiretroviral drugs, and other aspects of HIV virology to simulate HIV transmission. To use the HIV model, set the configuration parameter Simulation_Type to HIV_SIM.

HIV model framework

Typical compartmental models are described in Compartmental models and EMOD. The most simplistic method of modeling HIV would be to use an SI compartmental model (described in SI and SIS models). Recall that in an SI model, individuals are born with no immunity; once becoming infectious, there is no resulting immunity gained from the disease and individuals remain in the infectious stage for life. Some HIV modelers increased the complexity of their compartmental models by using an SIR model (described in SIR and SIRS models), but modify the compartments by replacing “Recovered/Removed” with “AIDS,” thereby creating an “SIA” model [Ref29]. Another option for increasing the fit of compartmental models is to add multiple stages of I, allowing for differentiation of the stages of HIV progression. This also enables the addition of ART to the model, where individuals can enter ART at different rates, and then return to survival rates that are similar to HIV- individuals [Ref30].

_images/HIV-SI.jpg

While EMOD is an agent-based model, individuals move through the infectious states analogously to the compartmental models described above. To account for the real-world complexity of HIV transmission, numerous parameters have been added to EMOD to increase its predictive power. Further, these parameters and their associated microsolvers allow EMOD to model aspects of HIV infections and population dynamics that do not readily fit into the SI framework (for example, the complexities that arise due to relationships and human contact networks). Finally, as an agent- based model, EMOD enables the addition of spatial and temporal properties to the simulation.

The following network diagram breaks down the model into various model components, and illustrates how they interact with one another. The components on the network diagram correspond to the structural components listed below. The following pages will describe in detail the general model functionality and how the structural components function.

_images/HIV-Model_Flowchart.png

Network diagram illustrating the HIV model and its constituent components.

The HIV simulation type adds a layer of HIV-specific biology to the general STI framework, which includes co- factors and interventions affecting transmission, as well as disease progression on and off therapy.

Cascade of care

By using campaign interventions and the appropriate event coordinator, it is possible to configure retention along a care continuum to model how individuals progress with detailed time-linked variables associated with access to care. For more information on configuring a cascade of care, see Cascade of care. For configuring HIV-specific treatment guidelines and cascades of care, such as participation in ART programs and associated drop-out rates, see Health care systems.

Individuals are guided through care cascades using individual properties, a very flexible and powerful feature of the model. With this feature, it is possible for you to create a set of tags for individuals in order to target them for events such as specific interventions, types of care, or even having a specific risk level. For more information on how individual properties, see Individual and node properties.

Model output and reporters

EMOD supports numerous methods for viewing simulation output. By default, every simulation creates an output report of aggregated data (see Overview of EMOD software for more information). While EMOD enables the creation of custom reports, the HIV model has an extensive list of available built-in reports. The reports are enabled in the config.json file (see Output settings for a complete list) and provide information on aspects of relationships and pair formation, infection status (including CD4 counts, WHO stage, and start and stop years), ART status, demographics, mortality, and other pertinent information. Note that it is important to keep track of which reports are enabled when running simulations, as some output files may not be desirable or appropriate with the simulation configuration. For example, Report_HIV_Infection creates a .csv file which logs the state of each individual at each time- step, so as the population grows or the simulation duration increases, this file will become extremely large and simulations can take much longer to complete.

The following pages describe the structure of the model and explore the model components. Additionally, the specifics of the model are discussed in detail in the articles Bershteyn, Klein, Wenger, and Eckhoff, arXiv.org, and Klein, Bershteyn, and Eckhoff, AIDS 2014.

Intrahost dynamics and HIV biology

The EMOD HIV model adds within-host HIV biology to the transmission modality of the STI person- to-person contact network. This allows the production of HIV-specific transmission rates, mortality rates, and the progression of biomarkers (such as CD4 count) specific to HIV-infected individuals. These factors can vary according to individual-specific traits, such as age, disease state, co- infection status, use of antiretroviral therapy, or other attributes.

The following sections describe how the model functions for untreated HIV. Treatment, such as health care and continuous enrollment on ART will alter the survival rates, and will be described in Health care systems.

Disease progression

The EMOD HIV model uses three stages of untreated HIV infection: acute, latent, and AIDS. The durations of acute and AIDS are configurable in the config.json file. The total survival time with HIV is sampled stochastically based on the individual’s age at the time of infection, and the duration of the latent stage is the total survival time minus the duration of the acute and AIDS stages. If the total survival time is shorter than the sum of the acute and AIDS stages, then the latent stage is eliminated and the AIDS stage is shortened as needed; in rare cases when survival is shorter than the acute stage, the remaining acute stage is shortened to fit within the survival duration and there is no AIDS stage.

Survival with untreated HIV infection

HIV prognosis is both heterogeneous and highly age-dependent, so survival is sampled from an age-dependent Weibull distribution, shown below.

_images/HIV-age-dependent-survival.jpeg

Age-dependent survival distribution for untreated HIV; figure reprinted from Bershteyn et al 2013.

Survival times for untreated HIV are determined at the time of infection using the above age- dependent distribution. There are different parameters used to configure the age distributions for children vs. adults, and the age at which an individual should no longer follow the children’s distribution can also be configured. The survival distribution for children is a convex combination of two Weibull distributions, to capture the bimodal nature of survival in children (children can be categorized as “rapid” or “slow” progressors). To configure this distribution, it is necessary to determine the fraction of children in each category, the decay rate of survival for rapid progressors, and the Weibull parameters for the slow progressors. For adults, the survival time is Weibull distributed, with older individuals having a shorter average survival time. These parameters are configured in the config.json file.

CD4 count

CD4+ T cells are immune system cells that fight off infection (see HIV disease overview for more information). Measuring the count of CD4 cells is a method to gage how well the immune system is functioning, or for HIV, to measure the progression of the disease. In the EMOD HIV model, CD4 count is initialized at a value that is selected from a Weibull distribution. During an untreated HIV infection, CD4 declines such that the square root of the count varies linearly between a starting point (the “post infection” point) and the count at death. This assumption of decline does not include the rapid and complex dynamics of CD4 counts during early HIV infection and during late-stage AIDS.

The survival time for untreated infection corresponds to the duration required for the change in CD4 count from initiation to end, and is used to determine the slope for declining CD4. However, some individuals may later initiate ART and survive longer than the time used to compute the slope.

The heterogeneity in CD4 count can be configured for the starting and ending counts; see Configuration parameters for more information. Because CD4 counts are Weibull-distributed parameters, the scale and heterogeneity can be configured. The scale parameters set the post- infection and at-death values, while the heterogeneity parameters are the inverse of the Weibull shape. Setting the heterogeneity to small values is equivalent to large shape parameters, and will result in a sharp peak near the scale value. Setting heterogeneity to zero will cause the initial CD4 count to be equal to the post-infection scale value.

WHO stage

The WHO has created clinical staging definitions to define and track the stages of HIV progression. Each WHO stage advances from 1 - 4 with transition times sampled from a Weibull distribution and is associated with declining bodyweight. In EMOD, both CD4 count and the current WHO stage influence the individual’s survival, although the WHO stage is not a configurable parameter. Note that WHO stage will determine eligibility for ART interventions. For more information, see Health care systems.

WHO stage is assumed to progress in proportion to an individual’s assigned survival time, but has added randomness to account for variability in HIV symptoms (and resulting ART eligibility) over a range of CD4 counts. Following a model by Johnson et al [Ref31], progression across WHO stage categories is divided into Weibull-distributed durations over the interval of survival, using the Weibull parameters tabulated below:

WHO stage transition

Shape

Scale

1 to 2

0.9664

0.26596

2 to 3

0.9916

0.19729

3 to 4

0.9356

0.34721

The WHO stage is generally considered an integer of 1, 2, 3, or 4. To provide additional information about how close an individual is to advancing to the next WHO stage, EMOD interpolates between transitions. For example, if an individual advances from WHO stage 1 to WHO stage 2 over the course of 100 days, the WHO stage on the 90th day will be 1.9. To obtain the expected integer value of WHO stage, the output should be rounded down. To examine WHO stage (and CD4 count) over time, it is possible to log each individual’s infection status with output reports. See HIV model overview for more information.

While the base infectivity parameter serves as the transmission rate for latent HIV, it is possible to modify the rate for the acute and AIDS stages of the disease. Disease stages have both a duration and multiplier that must be configured. During the latent stage, neither of the multipliers for the acute or AIDS stages are applied, and the duration of the latent stage is calculated by subtracting the durations of the acute and AIDS stages from the overall survival time. If individuals receive survival durations that are shorter than the sum of the acute and AIDS stage durations, then the latent stage is eliminated. The acute stage will receive the multiplier for its entire duration, and the AIDS stage will receive it’s multiplier for the remainder; should the survival time be shorter than the acute stage duration, the acute multiplier will be applied for the full survival duration.

Symptomatic presentation

Survival with HIV is highly dependent on receiving proper treatment with ART. Unfortunately, HIV symptoms typically are not diagnostic until the individual has reached the AIDS stage, which makes survival probability low. In EMOD, the model independently draws the time at which an individual may present for care due to AIDS-related symptoms. The time between symptomatic presentation and (untreated) AIDS-related death is assumed to be Weibull-distributed, and these parameters can be configured in the config.json file (see the “mortality and survival” section of Configuration parameters for more information).

Upon infection or ART discontinuation, the individuals draw from the configured Weibull distribution to determine the time between symptomatic presentation and untreated AIDS-related death. The duration is subtracted from the AIDS-related death date to determine the time of symptomatic presentation. Small values lead to symptomatic presentation close to the time of AIDS-related death, and large values lead to symptomatic presentation well before AIDS- related death. If the drawn time is longer than the total survival time, then the total survival time is used (i.e., symptomatic presentation occurs immediately upon infection). The date of symptomatic presentation has no direct impact on clinical progression; however, it can be used to configure health-seeking behavior.

Citations
Ref31

Johnson LF, Dorrington R. Modelling the demographic impact of HIV/AIDS in South Africa and the likely impact of interventions. Demographic Research 2006; 14:541–574.

Health care systems

Intervention campaigns in the EMOD HIV model typically involve health care, treatment, and access to care. Configuring campaigns involves the use of event coordinators, which determine who will receive the intervention; campaign events, which determine when and where interventions will be distributed; and the intervention itself, which determines what will be distributed. For HIV, these events and interventions can be configured to create a health care system, such that individuals with particular attributes are selected for particular types of care. For HIV, this system is termed the cascade of care, and involves testing, diagnosis, and treatment; individuals can leave and enter the cascade at multiple time points.

For more information on the cascade of care, see Cascade of care.

Restricting multiple entries into health care

Health care in EMOD is bi-directional: it can be applied to individuals, or it can sought by individuals in response to various triggering events including birth, sexual debut, pregnancy, or AIDS symptoms. A potential problem created by this structure is that an individual could end up in care multiple  times. For example, an individual might have an antenatal care (ANC) visit and, in the same time-step, seek health care for AIDS symptoms, both leading to HIV testing and staging.

The HIVMuxer intervention is a method that can be used to prevent this problem. HIVMuxer counts the number of times an individual is simultaneously waiting in the same delay state or group of delay states and restricts the number of entries that individual is eligible to receive.

Diagnostics and testing

To route individuals into the care and treatment systems, it is necessary to use diagnostic testing. EMOD has multiple types of diagnostics, which can be found in Campaign parameters. The outcomes of different diagnostic tests can be used to initiate treatment, prevention services, entrance into health care systems, or lead to knowledge (such as HIV status) that will change the individual’s behavior. Testing can be triggered by a variety of factors, such as age, time of sexual debut, onset of symptoms, pregnancy, or simply through voluntary/routine testing. The triggers can be configured in the different types of diagnostics, and different results can be used to initiate care. Tests also have a probability of being wrong, such that some individuals that test negative may in fact be positive for the disease.

Decisions

Individuals can be enrolled in treatment due to the outcomes of diagnostic testing, but EMOD also allows for individuals to make decisions about treatment. These decisions can be based on factors such as time, age, the individual’s current state or sexual debut status, or even a random choice.

For individuals making a random choice, EMOD will base the decision on a random coin flip, or if more than 2 choices are configured in the campaign file, a dice roll. All choices and their outcome probabilities are configurable; should the sum of the probabilities not equal 1, then EMOD will normalize the sum to 1, while keeping their relative proportions the same.

The HIVRandomChoice class allows you to configure an array of options and the probabilities for each outcome. In those cases, the probabilities are not dependent on the number of choices, but must still sum to 1.

History of past treatment guidelines

The results of diagnostic tests are used to route individuals to treatment, with target levels for CD4 counts, WHO stage, or other factors used to determine the course of action for the individual. Over the past several decades, such treatment guidelines have changed, and EMOD allows for these changes in guidelines to be incorporated into the diagnostics. For example, cut-off values for CD4 counts by age and pregnancy status to determine eligibility for treatment have expanded in South Africa over the past 20 years. Configuring InterpolatedValueMap (which consists of arrays of Times and Values) for their appropriate parameters will let the model utilize these different diagnostic levels in the appropriate years.

The below JSON (JavaScript Object Notation) example shows the HIVARTStagingCD4AgnosticDiagnostic intervention class, where several parameters demonstrate configuring past history guidelines. For example, Adult_By_WHO_Stage has different WHO stage category recommendations for ART eligibility depending on year, and Child_Treat_Under_Age_In_Years_Threshold shows how the age at which children were eligible for ART changed over time.

{
    "class": "CampaignEvent",
    "Event_Name": "OnART1-triggered piecewise event",
    "Start_Day": 1,

    "Nodeset_Config": {
        "class": "NodeSetAll"
    },

    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Event_Name": "DrawBlood constant test, broadcasts HIVPositiveHIVTest",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "class": "NodeLevelHealthTriggeredIV",
            "Trigger_Condition_List": ["HIVNeedsHIVTest"],

            "Demographic_Coverage": 1,
            "Duration": 14600,

            "Actual_IndividualIntervention_Config": {
                "class": "HIVARTStagingCD4AgnosticDiagnostic",
                "Positive_Diagnosis_Event": "HIVPositiveHIVTest",
                "Base_Specificity": 0,
                "Base_Sensitivity": 0,
                "Cost_To_Consumer": 10,
                "Days_To_Diagnosis": 5,
                "Disqualifying_Properties": ["InterventionStatus:InterventionStatus_1", "InterventionStatus:InterventionStatus_2", "InterventionStatus:InterventionStatus_3"],
                "New_Property_Value": "InterventionStatus:InterventionStatus_4",
                "Individual_Property_Active_TB_Key": "HasActiveTB",
                "Individual_Property_Active_TB_Value": "YES",
                "Adult_Treatment_Age": 1865,
                "Adult_By_WHO_Stage": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        4.1, 2, 3, 4
                    ]
                },
                "Adult_By_TB": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        0, 1, 1, 1
                    ]
                },
                "Adult_By_Pregnant": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        1, 1, 1, 0
                    ]
                },
                "Child_Treat_Under_Age_In_Years_Threshold": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        1, 2, 5, 3.2
                    ]
                },
                "Child_By_WHO_Stage": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        1.1, 1.5, 2, 2.5
                    ]
                },
                "Child_By_TB": {
                    "Times": [
                        1990, 1995, 2000, 2005
                    ],
                    "Values": [
                        1, 1, 1, 0
                    ]
                }
            }
        }
    }
}
Antiretroviral therapy (ART)

Survival time for untreated HIV is described in Intrahost dynamics and HIV biology, with individuals progressing through the three diseases stages (acute, latent, AIDS). Antiretroviral therapy (ART) significantly alters this progression and impacts survival in a positive way (for more information on ART, see HIV disease overview). In EMOD, survival time on ART is assumed to follow a Weibull proportional hazards model published by May et. al. with the IeDEA Southern Africa collaboration [Ref32]. The hazard ratios are applied proportionally to weight and CD4 count (at initiation of ART for both), and are applied categorically to WHO stage (at initiation of ART), gender, and age. Body weight is assumed to be linked to WHO stage progression, with linearly declining body weight between each transition.

The hazard ratios are shown in the following tables:

Category

Hazard ratio base

Hazard ratio multiplier

Body weight at initiation

21:1

0.93 per kg

CD4 count at initiation

1:32

0.9925/cell/uL up to 350 cells/uL

Continuously applied hazard ratios

The reduction in hazard of death per increase in CD4 count is capped at a CD4 count of 350 cells/uL, such that individuals initiating at CD4 counts greater than 350 cells/uL receive the same CD4-related hazard adjustment as those with a CD4 count of 350 cells/uL. In other words, the model currently makes a conservative assumption that the health benefit of initiating at CD4 counts greater than 350 cells/uL is identical to that of initiating at exactly 350 cells/uL.

Category

Value

Hazard ratio

WHO stage

3 or 4

2.71

Gender

Female

0.68

Age

>40 years

1.43

Categorically applied hazard ratios

There are multiple campaign classes that are used to implement ART programs in the model. To enroll individuals on ART, the ARTBasic intervention is applied. To remove individuals from ART, the ARTDropout intervention is applied. Note that both of these interventions will only impact individuals that are HIV+; in order to use ART as a prophylactic, the SimpleVaccine class must be used (see Pre-exposure prophylaxis). Finally, eligibility for ART can be determined through two classes, HIVARTStagingCD4AgnosticDiagnostic and HIVARTStagingByCD4Diagnostic. When using CD4-dependent ART interventions, it is important to use the HIVDrawBlood intervention first, as this acts analogously to performing phlebotomy and logs an HIV-infected individual’s current CD4 count.

Note that the multiplicative effect of ART for reducing HIV transmission is set in the configuration file, while the campaign interventions used determines who receives the effects of ART and at what time periods. See Transmission for more information on STI transmission and the factors that influence it.

ART’s impact on CD4 count

CD4 count declines with advancing HIV disease progression, but CD4 counts can be reconstituted with ART. The Swiss HIV Cohort Study demonstrated that absolute changes in CD4 counts from the baseline measurement are consistent over the first few years of ART, independent of the baseline value. For example, a patient starting with a CD4 count of 100 cells/uL, will, on average, reconstitute to 200 cells/uL in the same time that a patient starting at 200 cells/uL will reconstitute to 300 cells/uL. This reconstitution rate follows a quadratic increase that saturates over three years, and can be calculated with the equation,

CD4 count increase = 15.584 x (months since initiation) - 0.2113 x (months since initiation)^2

Interruption of ART will initiate a decline in CD4 count, and resumption of ART will then initiate another reconstitution of CD4. EMOD calculates survival time on ART discontinuation by first determining what the survival time would have been for a newly infected individual at the age when discontinuation occurred, and then adjusts the time to account for potentially low CD4 at discontinuation using the following equation:

% survival time applied at ART discontinuation = (CD4 at discontinuation)/(CD4 at infection)

The slope of CD4 decline is comparable to a newly infected individual, but the infection is “fast-forwarded” proportionally to the loss of CD4 count relative to a newly infected individual.

When ART is re-initiated, survival is drawn from the distribution corresponding to the updated CD4 count and age at re-initiation. Mortality rates on ART are modeled as Weibull distributions with a shape parameter <1, which produces a “super-exponential” mortality curve (i.e. one with a probability density function that declines more rapidly than an exponential distribution). This produces an elevated mortality rate soon after ART initiation, and a lower mortality rate as time on ART increases. Discontinuation and re-initiation of ART produces higher mortality rates than continuous ART by repeatedly exposing the individual to this high early mortality rate.

_images/intrahost.png

An example of CD4 counts and prognosis for a patient on and off ART. Art by Samantha Zimmerman.

Pre-exposure prophylaxis

Antiretroviral therapy as treatment for HIV was explained above, in Antiretroviral therapy (ART). ART can also be used as pre-exposure prophylaxis (PrEP), to prevent the transmission of HIV. In EMOD, the ART interventions are only used for treatment for HIV+ individuals, so to use ART as a prophylactic, it is treated as a “vaccine” and the vaccine intervention classes are used.

Citations
Ref32

May M, Boulle A, Phiri S, et al. Prognosis of patients with HIV-1 infection starting antiretroviral therapy in sub-Saharan Africa: a collaborative analysis of scale-up programmes. The Lancet 2010; 376:449–457

Citations
Ref29

Jun-jie, et al, 2010. Dynamic mathematical models of HIV/AIDS transmission in China. Chin Med J. 123(15): 2120-2127. https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5523934/

Ref30

Williams. 2014. Fitting and projecting HIV epidemics: Data, structure, and parsimony. https://arxiv.org/ftp/arxiv/papers/1412/1412.2788.pdf

HIV disease overview

IDM is committed to utilizing modeling approaches and quantitative analysis to explore how interventions can act to reduce the burden and transmission of HIV. This page provides information about HIV itself: the biology, symptoms, treatment, and prevention. See HIV model overview for information about the Epidemiological MODeling software (EMOD) HIV simulation type developed by IDM to aid in HIV control.

About HIV

The human immunodeficiency virus (HIV) attacks the immune system by targeting CD4 positive T cells, which are white blood cells that serve a crucial role in regulating immune response and fighting off infection. When left untreated, HIV drastically reduces the number of CD4 cells, severely weakening the immune system and enabling opportunistic infections and cancers. Once the level of CD4 cells drops below a threshold, HIV develops into AIDS (acquired immunodeficiency syndrome), the most severe phase of an HIV infection. There is no cure for HIV, but it is possible to treat and control the virus. Untreated individuals with HIV/AIDS have an average survival of 9-11 years post- infection, however with proper treatment, infected individuals can live a normal lifespan.

_images/HIV-infected-TCell.jpg

Scanning electromicrograph of an HIV-infected T cell. Image credit NIH, “HIV/AIDS”.

HIV virology

HIV is a retrovirus. Retroviruses are RNA viruses that are obligate parasites, requiring the host-cell’s machinery to produce new viral particles. Once inside the host cell, the virus uses its own reverse transcriptase enzyme to produce DNA from its RNA genome. The virus integrates viral DNA into the chromosomal DNA of the host cell, becoming a permanent part of the host genome. The cellular machinery of host cells is sequestered by the virus to replicate new viral particles.

HIV is a particular type of retrovirus called a lentivirus. Characterized by long incubation periods, these viruses cause chronic and deadly diseases in mammals; in primates, they target CD4 proteins of the immune system. Host cells are destroyed in the process of viral replication, causing a significant reduction in immune system cells as viral load increases. As these vital immune system cells are destroyed, cell-mediated immunity is lost and the individual becomes increasingly susceptible to opportunistic infections.

For more details on how viral replication works, see HIV replication cycle.

Viral structure and genome
_images/HIV-Virus-Structure.png

Illustration of the viral structure of HIV; image credit Microbe Online, “Structure of Human Immunodeficiency Virus (HIV)”.

HIV is a spherical retrovirus with a typical diameter between 100 and 130 nm–about 60 times smaller than a red blood cell. A viral envelope, or lipid membrane, encloses the virion. Embedded in this lipid membrane are 72 envelope proteins, glycoproteins, which spike through the membrane. These surface proteins, gp120 and gp41, are responsible for viral attachment and entry to host cells. Differences in gp120 are used for identifying HIV types, namely HIV-1 versus HIV-2, and their subtypes (see HIV types for more information).

Within the membrane is a capsid, which contains enzymes and genetic material. The enzymes, required for virion replication, are reverse transcriptase, proteases, ribonuclease, and integrase. The virion’s genetic material is comprised of two copies of single-stranded RNA, which has 9 genes encoding 19 proteins. Three genes code for structural proteins required for creating new viral particles. The remaining 6 genes code for proteins that are involved in HIV’s ability to infect new cells, replicate, or cause disease.

The structural genes:

  1. Group-specific antigen (Gag): responsible for the core structural proteins of the virus

  2. Envelope (Env): responsible for gp120 and gp41

  3. Polymerase (Pol): responsible for reverse transcriptase, integrase, protease

The Regulatory genes:

  1. Tat: responsible for activation of transcription of viral genes (required for replication)

  2. Rev: responsible for transport of late mRNAs from the nucleus to cytoplasm (required for replication)

  3. Nef: Decreases CD4 and MHC class I protein expression in virus-infected cells

  4. Vif: Enhances viral infectivity

  5. Vpr: Transports the viral core from the cytoplasm into the nucleus

  6. Vpu: Enhances virion release from the host cell

_images/HIV-genome.png

Diagram illustrating the structure of the HIV genome. Image credit Wikipedia “HIV - Structure and genome”.

HIV replication cycle

The replication process to create new HIV virions occurs in three phases. First, the virus needs to enter the host cell. Second, replication of viral genetic information occurs within the host cell. And third, and finally, new virions are assembled and released from the host cell.

Ultimately, host cells are destroyed by HIV infection, but this destruction is not the result of the release of mature virions. Instead, infected cells appear to sacrifice themselves through a highly inflammatory form of apoptosis called pyroptosis [Ref1], [Ref2]. Unfortunately, pyroptosis tends to lure more CD4 cells to an area, which propagates the infection-destruction cycle, and increases the damage done to the immune system.

The following diagram illustrates the cycle of HIV viral replication.

_images/HIV-replication-cycle.jpg

HIV replication cycle, adapted from NIAID and the NIH HIV/AIDS.

Let’s explore the cycle in more detail:

Phase I: Cellular entry

In order to enter a host cell, the HIV virion uses the glycoproteins on its surface to attach to the target cell. Gp120, the distal portion “spike” complex, binds to CD4 receptors (especially on T-cells). After binding, a cascade of conformational changes occurs in gp120 and gp41, and the virion fuses with the host cell’s membrane. Once fusion is complete, the capsid (which contains the RNA, reverse transcriptase, proteases, ribonuclease, and integrase) is injected into the host cell. This process is represented in steps one and two in the above figure.

Phase II: Replication

Once the viral capsid enters the host cell, the viral reverse transcriptase acts to copy the viral RNA into cDNA. The ribonuclease then acts to degrade the viral RNA, and the polymerase creates a complement to the single stranded cDNA; the newly-formed double-stranded viral DNA is then transported into the host cell’s nucleus, where integrase integrates it into the host cell’s genome. This process is represented in steps three, four, and five in the above figure.

It is worth noting that the process of reverse transcriptase is extremely error-prone. The mutations arising out of these copying errors are thought to contribute to the development of drug resistance and to also enable the virus to escape detection by the immune system.

Once the viral DNA has integrated into the cell’s genome, the cell uses it’s own machinery to transcribe viral DNA into viral RNA. This viral RNA is either used to build new HIV proteins, or serves as the genome of new virions.

Phase III: Assembly and release

Once the new copies of viral proteins and genomic RNA have been created, they move to the surface of the host cell. Viral structural proteins (created from the Gag gene) associate with the inner surface of the host cell, causing a new virion to start forming and bud from the cell. Within the bud, or the immature virion, are more structural proteins necessary for capsid formation and the viral genome. As the bud progresses, viral proteases cleave the structural components so they can be assembled to form a the capsid and other capsid enzymes. The process is completed when the bud is cleaved from the host cell (mediated by viral proteases), and results in the release of mature virions. This process is represented in steps six and seven in the above figure.

HIV types

A hallmark of HIV is the high level of genetic variability the virus exhibits, which can make treatment very difficult. There are two main types of genetically distinct HIV: HIV-1 and HIV-2, and each type can further be broken down into groups and subgroups. HIV-1, the first to be discovered, is the more common and more virulent strain of HIV. HIV-2 is less transmissible, and is primarily found in western Africa (although cases are becoming more common in India, and incidence–while still low–is on the rise in some parts of Europe and the Americas [Ref3]). Both types follow the same transmission route and have the same pathology–both may develop into AIDS. Co-infection, or infection with both HIV-1 and HIV-2, is possible.

_images/HIV-SIV-phylogenetic-tree_straight.png

The phylogenetic tree of HIV and SIV (simian immunodeficiency virus), with types and groups labeled. Image credit: Thomas Splettstoesser (www.scistyle.com), https://commons.wikimedia.org/wiki/File:HIV-SIV-phylogenetic-tree.svg

HIV-1

HIV-1 is the more prevalent form of HIV, and most information about HIV/AIDS is in reference to HIV-1. This type is the more virulent, or pathogenic, type: it is highly transmissible and individuals develop AIDS when it is not treated.

HIV-1 can be broken down into a major group, Group M, and up to three minor groups, Group N, O, and P. It is thought that each of these groups corresponds to an independent transmission event of SIV (simian immunodeficiency virus) into humans [Ref4].

The major group, M, comprises over 90% of HIV/AIDS cases. It can further be divided into 11 subtypes, A through K. Recombination between subtypes can also occur, further increasing genetic diversity of HIV.

Many of the subtypes have been identified due to differences in the envelope (env) region–the genes that code for gp120 and gp41.

HIV-2

HIV-2 is less transmissible than HIV-1, and individuals infected with HIV-2 are less likely to develop AIDS. Disease progression is slower, and in some cases infected individuals may remain lifelong non-progressors. Clinically, those with HIV-2 tend to have higher CD4 counts and lower viral loads than those with HIV-1.

HIV-2 has 8 known subgroups: A through H. Currently, only A and B are pandemic, however HIV-2 is predominantly found in western Africa.

Genetic variability

HIV is difficult to treat, largely due to how genetically diverse it is, and how rapidly it can increase diversity. This arises due to multiple reasons:

  • HIV has a high replication speed. The virion burst size, or number of virions produced per infected cell, ranges from 1,000 - 3,000 [Ref5], or approximately 10^10 virions per day. For reference, the burst speed for influenza (when reared in chicken egg cells) is about 500 - 1,000. This means that a huge number of virions are present within an individual, and the numbers increase drastically over short amounts of time. Each virion produced is a potentially new variant.

  • HIV has a high mutation rate. HIV can mutate at a rate of 3 x 10^-5 per nucleotide base per cycle of replication. For reference, DNA viruses have a mutation rate of 10^-6 to 10^-8 per base per generation. The human genome (as a whole) mutates at approximately [Ref6] 1.1x10^-8 per base per generation. With a high mutation rate, the numerous virions produced per day have the potential to be quite variable, and variation can increase quite rapidly.

  • Reverse transcriptase is error prone and has recombinogenic properties [Ref7], [Ref8]. The high error rate of transcription with reverse transcriptase contributes to the high mutation rate seen in HIV. However, reverse transcriptase is also highly recombinogenic: there are two copies of RNA packaged in the capsid of the virion, and reverse transcriptase has the ability to “jump” between each of the copies; this creates crossovers during the replication cycle, and when co-infection occurs in a cell, novel or hybrid genomes may be created.

HIV symptoms and disease stages

Unfortunately, there are no distinctive symptoms used to diagnose HIV. The only definitive method of diagnosis is through testing. Some individuals may experience flu-like symptoms (such as fever, chills, rash, night sweats, achy muscles, sore throat, fatigue, etc) in the first 2-4 weeks after infection, but not every infected individual experiences symptoms, and these symptoms are not conclusive. For those experiencing symptoms, they may persist for a few days up to several weeks. In this early period, HIV tests may not yield a positive result even though the person is infectious. For more on HIV tests, see Testing.

For more on symptoms, see www.hiv.gov.

Once infected with HIV, there are three stages to the disease, explained in detail below.

Stage 1: Acute HIV infection

Two to four weeks after infection, individuals may experience flu-like illness. In this stage, individuals are very infectious as the virus is replicating rapidly.

Stage 2: Clinical latency

Also known as HIV inactivity or dormancy, asymptomatic HIV infection, or chronic HIV infection. During this period, the virus is still active but reproduction has slowed, and typically no symptoms are exhibited. The duration of this stage is incredibly variable: for some, it may last a decade or more; for others, it could be much shorter. Individuals are still infectious in this stage.

Stage 3: AIDS

One HIV progresses to AIDS (acquired immunodeficiency syndrome), the disease has reached its most severe phase, and is characterized by progressive failure of the immune system. Because the immune system is severely damaged, individuals succumb to increasing numbers of severe illnesses (opportunistic infections). Without treatment, survival with AIDS is roughly 3 years. Diagnosis of AIDS can be by CD4 cell count: individuals with AIDS have CD4 counts of < 200 cells/mm^3 (compared to healthy individuals, with CD4 counts of 500 - 1600 cells/mm^3). In this stage, individuals are extremely infectious and have very high viral loads.

Transmission

Many myths–and stigmas–persist around how HIV is transmitted. Understanding how it is–and is not–transmitted is key for the success of control efforts.

It is not possible to become infected with HIV through non-sexual contact with infectious individuals, nor by sharing an environment with them. HHIV does not survive long outside of the human body, so it CANNOT be transmitted through:

  • The environment, such as through air or water

  • Vectors, such as biting insects or other animals

  • Sharing toilets, touching surfaces exposed to infectious individuals

HIV is specific to particular body fluids, and does NOT live in saliva, sweat, or tears; it is not possible to become infected through contact with those fluids, nor by sharing food or drink with infectious individuals.

HIV has specific transmission routes and it only survives in particular bodily fluids: blood, semen, pre-seminal fluid, rectal and vaginal fluids, and breast milk. To get infected with HIV, infected fluids must come into contact with a mucous membrane or damaged tissue, or by being injected into the bloodstream (e.g. with shared needles).

The most common routes of HIV transmission are:

  • As an STI (with anal sex as the riskiest type of sex for HIV transmission)

  • Vertical transmission: from mother to child during pregnancy, birth, or through breastfeeding

  • From shared needles/syringes

  • Contact with open wounds (when contact is on damaged tissue)

  • Through blood transfusions/organ donations (when the donor blood was infectious)

While certain behaviors can increase risk of HIV (such as unprotected sex or sharing needles), other factors, such as co-infection with other STDs, can also increase the chances of HIV transmission. People with STDs are 3 times as likely to get HIV by having unprotected sex with an HIV+ person. This is because STDs can cause irritation of the skin, sores, etc, which makes it easier for HIV to enter the bloodstream. Even just irritation of the genital areas can increase the risk, as it increases the number of cells that can serve as targets for HIV. Conversely, HIV+ people with an STD are 3 times more likely as other HIV+ people to spread HIV through sexual contact. This is because having an STD causes an increased concentration of HIV virus in the semen & genital fluids.

Treatment and prevention of transmission

There is no cure for HIV, but with proper treatment, those infected with HIV can now live normal lifespans. Additionally, there are treatments that will prevent transmission, which can be especially important for serodifferent partners.

There are multiple options to reduce the risk of HIV transmission:

  • Always use condoms with new partners, HIV+ partners, or those whose serology is unknown. In addition, always use proper lubricants.

  • Reduce your number of sexual partners.

  • Use PrEP (see below) for those that are at risk of contracting HIV.

  • Use PEP or ART if you have been exposed.

  • Get regularly tested and treated for STDs.

  • Encourage HIV+ partners to remain on treatment.

  • Male circumcision: circumcision reduces the risk of men getting HIV from HIV+ female partners.

PrEP

Pre-exposure prophylaxis, or PrEP is a daily medication that, when taken properly, reduces risk of HIV by 90% (70% for those using injectable drugs) [Ref19]. PrEP is a pill that combines two nucleoside reverse transcriptase inhibitors (NRTIs) (tenofovir, emtricitabine), both of which are used in some ART combinations. PrEP should be taken by individuals that are at high risk of contracting HIV.

PrEP reaches its maximum protection effectiveness at about 7 days of daily use for receptive anal sex, and at about 20 days of daily use for receptive vaginal sex and injective drug use. Currently, there little to determine how long it takes to reach maximum protection for insertive anal or insertive vaginal sex; current information can be found with the Risk Reduction Tool.

For more information on PrEP, see CDC, What is PrEP, and We > AIDS.

ART

While there is no cure yet for HIV, antiretroviral therapy (ART) can be used to control HIV in infectious individuals. ART is a daily pill taken by HIV+ individuals, and is comprised of a combination of 3 medications which work to prevent the HIV virus from replicating. These combinations are comprised of nucleoside reverse transcriptase inhibitors (NRTIs), nonnucleoside reverse transcriptase inhibitors (NNRTIs), protease inhibitors, entry inhibitors, and integrase inhibitors. Using a multi-faceted approach with different drug combinations has helped prevent drug resistance in patients.

The sooner a patient beings taking ART, the better the treatment and control of HIV. The START study found that when treatment begins while CD4 counts are still relatively high, patients have a significantly reduced risk of developing AIDS. Further, everyone with HIV should be on ART, regardless of CD4 count: early results have shown that the risk of serious illness or death can be reduced by 53% in an early treatment group versus a deferred treatment group [Ref9].

ART should also be taken to help prevent transmission from infectious to uninfected individuals. The HPTN 052 study found that ART can reduce the risk of HIV transmission by 93%, and early ART can prevent HIV transmission. ART prevents transmission by reducing viral load to undetectable levels. Recent work by Rodger et al [Ref10] found that individuals on ART with a zero viral load did not transmit HIV to their partners. However, caution should still be taken as HIV is theoretically still transmissible, despite having undetectable viral loads. HIV can still exist in semen, vaginal or rectal fluids, breast milk, or other parts of the body–viral load tests only measure viral load in blood (see Testing). Further, viral load may increase between tests, making transmission possible even after a test with an undetectable load. Finally, STDs increase viral load in genital fluids; so having an STD and HIV may increase risk of transmitting to partners even if viral load is undetectable in blood.

PMTCT

As of 2015, there are an estimated 1.8 million children (under the age of 15) living with HIV [Ref11]. The majority of cases in children occur through vertical transmission, where HIV was transmitted to the child from an HIV+ mother during pregnancy, childbirth, or breastfeeding. Prevention of mother-to-child transmission (MTCT) programs, or PMTCT, aim to reduce these numbers drastically. According to the WHO, globally there were over 1.4 pregnant women with HIV in 2016; left untreated, the risk of HIV transmission to their children can be as high as 45% [Ref12]. Fortunately, the risk of MTCT is reduced to less than 5% when women are on ART [Ref11], and PMTCT programs have been largely successful: an estimated 76% of HIV+ pregnant and breastfeeding women received antiretroviral drugs in 2016.

Despite progress with these programs, there is still much room for improvement. In 2015 an estimated 150,000 children were infected with HIV [Ref11], and by the end of 2016, only about 43% of infected children had access to ART. For children born with HIV, 50% of them will not survive past the age of two [Ref11] without treatment.

For more information on the global PMTCT plans, targets, and progress, see Avert.

90-90-90

The driving goal for HIV is to end the global AIDS epidemic. To achieve this, UNAIDS has created an ambitious target program called “90-90-90.” Under these guidelines, the goal is that by the year 2020, 90% of all people living with HIV will know their status; 90% of all people with a diagnosed HIV infection will receive sustained ART; and 90% of all people on ART will have viral suppression [Ref13].

Achievement of these goals will facilitate ending the worldwide AIDS epidemic by 2030. When the targets are reached, 73% of all people living with HIV will be virally suppressed–a roughly two- to three-fold increase over current estimates viral suppression [Ref13]. Testing is a key step in acheving these goals, as many people living with HIV are unaware of their status. In 2014, a report by UNAIDS found that approximately 54% of people were unaware of their positive infection status. Fortunately, current estimates are higher, with roughly 70% of people aware of their HIV status; an additional 7.5 million people need to access testing to reach the 90% target [Ref18]. To achieve viral suppression, individuals living with HIV need to have reliable access to treatment. In 2016, approximately 53% of adults and 43% of children living with HIV had access to treatment [Ref14]. With the 90-90-90 goals, these numbers are expected to increase rapidly.

However, while universal test and treat remains an important component of combination HIV Prevention [Ref15], [Ref16], there is growing skepticism as to whether the 90-90-90 goals, and universal test and treat in general, will be sufficient to end the epidemic [Ref17].

Testing

Testing is the only definitive method for diagnosing HIV infection, making it the important first step for care. According to the CDC, everyone between the ages of 13-64 should be tested at least once during routine care. Those at higher risk of HIV exposure should get tested more frequently, such as every 3-6 months. No test is able to detect HIV immediately after exposure, so testing regimes need to be conducted on appropriate time-scales.

There are three main types of tests currently in use; note that any positive test, regardless of type, requires a follow-up test (usually in a lab) to confirm the results.

  1. Nucleic acid testing (NAT): These test for virus in the blood, and is also known as a viral load test. These tests tend to be more expensive than other methods, and are not commonly used in routine testing. These tests are accurate during the early stages of infection, and can detect HIV 10 - 33 days after exposure.

  2. Antigen/antibody tests: These test for the presence of HIV antibodies and antigens. When the test is conducted in a lab using blood from a vein, they are able to detect HIV 18 - 45 days after exposure. When the test is conducted using a finger prick, they are able to detect HIV 18 - 90 days after exposure.

  3. Rapid tests and home tests: These tests are also antibody tests, and typically rely on blood from a finger prick or oral fluid. These tests have been designed to facilitate fast turnaround for results.

    1. Some rapid tests are laboratory antibody tests; they utilize vein-drawn blood, and results take several days.

    2. Rapid antibody screening tests can be ready in less than 30 minutes, and are used in both clinical and non-clinical settings. These tests typically use a finger-prick or oral fluid.

    3. Oral fluid antibody self-test: these tests have been designed for ease of use, so that the patient can test themselves. An oral swab is used, and results can be ready in as little as 20 minutes; these tests are used at home, in clinics, or in community testing centers.

    4. Home collection kits. These kits are designed to be used in the home; the patient takes a finger prick, sends the test to a lab, and can get the results by the next day.

Global HIV burden and statistics

The HIV/AIDS epidemic reached peak mortality in 2005, with 2.6 million deaths [Ref14]. Since the start of the epidemic, the WHO estimates that over 70 million people have been infected, and 35 million have died. Global efforts at prevention and control have been largely successful in reducing the numbers of infections, and even more successful in reducing mortality due to HIV. However, despite these efforts and advances, there is still much work to be done for HIV control.

The Institute for Health Metric Evaluation at the University of Washington tracks mortality and disease burden for HIV/AIDS with their Global Burden of Disease (GBD) study. Despite the enormous increases in funding, HIV/AIDS remains in the top 10 causes of mortality worldwide, and success in prevention, treatment, and control efforts varies dramatically by country. As of the end of 2016, there are upwards of 34 million adults–approximately 0.8% of adults aged 15-49 worldwide–living with HIV [Ref18], and almost 2 million children living with HIV [Ref19]. Sub-Saharan Africa is the most seriously impacted region, with close to 1 in every 25 adults (4.2%) living with HIV; this accounts for almost 2/3 of all worldwide cases [Ref18].

_images/Num-people-HIV.png

The number of people worldwide living with HIV in 2016, broken down by global region. Image credit: Avert.

Because HIV cannot be cured, there have been immense efforts placed on prevention of new infections. As of 2016, there are still around 2 million new cases in adults [Ref20] and 150,000 cases in children each year [Ref11]. Despite the high numbers of individuals living with HIV, prevention efforts have been successful, as overall disease incidence is down. Since 2000, there has been a 35% decrease in adult infections and 58% decrease in infections in children [Ref21].

_images/New-infections-since-2010.png

The number of new HIV infections in 2016 and the percentage change of infections since 2010. Image credit: Avert.

In addition to prevention of new infections, control of HIV has also focused on the care of individuals living with HIV, in order to reduce mortality. Approximately 1 million people still die each year from HIV-related illnesses [Ref18]. While this number is unfortunately large, it is actually a 42% decrease from the peak deaths in 2004/2005 [Ref21].

Much of the success in prevention and treatment of HIV stems from advances in medication, namely the antiretrovirals that are available. There has been an 84% increase in access to ART since 2010 [Ref21]. Access to ART, combined with the global response to HIV, is responsible for averting roughly 30 million new infections and almost 8 million deaths since 2000 [Ref21]. The progress is remarkable, but the effort continues to halt the spread of HIV.

Benefits of mathematical modeling in the control of HIV

Ending the AIDS epidemic is a formidable challenge that requires a multifaceted and multi- disciplinary approach. While HIV treatment and prevention efforts are crucial components, mathematical modeling also plays a vital role. In general, modeling and quantitative analysis can provide insight into key factors influencing transmission dynamics and serve as the groundwork for evidence-based policy- and decision-making.

Modeling approaches have proven to be invaluable for understanding HIV transmission and developing control strategies. As resources are often limited, modeling can be used to evaluate intervention strategies and their potential impacts on HIV transmission [Ref22] before programs are implemented. This can provide insight into the cost and cost-effectiveness of treatment programs [Ref23], [Ref24], and help determine the ways in which to most effectively use available resources. Further, modeling can help to identify particular risk groups and target populations that may have the largest impact on disrupting HIV transmission [Ref25]. And conversely, models can highlight how targeting particular risk groups for interventions will not provide enough impact to disrupt transmission, and is in fact, “too little too late” [Ref26]. Finally, modeling was instrumental in determining the population-size targets for global interventions: the 90-90-90 program (see 90-90-90) utilized models to determine how many people need to gain access to care in order to end the AIDS epidemic, and, when those targets are adhered to, when the epidemic should end [Ref13].

Controlling HIV/AIDS requires not just population-level understanding of transmission dynamics, but a thorough comprehension of within-host dynamics as well. Fortunately, mathematical models have also proven valuable for this, by elucidating the impact and interactions HIV has on the immune system. Further, models are able to help determine effects of particular drug treatments [Ref27], and to identify optimal drug therapy regimes [Ref28].

Further resources

Citations

Ref1

Doitsh et al., 2013. Cell death by pyroptosis drives CD4 T-cell depletion in HIV-1 infection. Nature, doi:10.1038/nature12940

Ref2

Monroe et al., 2013. IFI16 DNA sensor is required for death of lymphoid CD4 T cells abortively infected with HIV. Science, doi:10.1126/science.1243640

Ref3

aidsmap, http://www.aidsmap.com/HIV-1-and-HIV-2/page/1322970/

Ref4

Sharp, P. M.; Hahn, B. H., 2011. Origins of HIV and the AIDS Pandemic. Cold Spring Harbor Perspectives in Medicine. 1 (1): a006841–a006835. doi:10.1101/cshperspect.a006841. PMC 3234451 Freely accessible. PMID 22229120.

Ref5

http://book.bionumbers.org/how-many-virions-result-from-a-single-viral-infection/

Ref6

Roach JC, Glusman G, Smit AF, et al., 2010. Analysis of genetic inheritance in a family quartet by whole-genome sequencing. Science. 328 (5978): 636–9. doi:10.1126/science.1186802. PMC 3037280 Freely accessible. PMID 20220176

Ref7

Reeves, Jacqueline D. and Derdeyn, Cynthia A. Entry Inhibitors in HIV Therapy. Boston: Birkhauser Verlag, 2007.

Ref8

Domingo, Esteban; Parrish, Colin R.; and Holland, John J. Origin and Evolution of Viruses. New York: Elsevier, 2008.

Ref9

Strategic Timing of AntiRetroviral Treatment (START) study: https://www.nih.gov/news-events/news-releases/starting-antiretroviral-treatment-early-improves-outcomes-hiv-infected-individuals

Ref10

Rodger et al, 2016. Sexual activity without condoms and risk of HIV transmission in serodifferent couples when the HIV-positive partner is using suppressive antiretroviral therapy. JAMA 316(2): 171-181.

Ref11(1,2,3,4,5)

UNAIDS, Children and HIV fact sheet. http://www.unaids.org/sites/default/files/media_asset/FactSheet_Children_en.pdf

Ref12

Avert.org, Prevention of Mother-to-Child Transmission (PMTCT) of HIV. https://www.avert.org/professionals/hiv-programming/prevention/prevention-mother-child

Ref13(1,2,3)

UNAIDS, 90-90-90 - An ambitious treatment target to help end the AIDS epidemic http://www.unaids.org/en/resources/documents/2017/90-90-90

Ref14(1,2)

UNAIDS, HIV fact sheet http://www.unaids.org/en/resources/campaigns/globalreport2013/factsheet

Ref15

Eaton JW, Johnson LF, Salomon JA, Bärnighausen T, Bendavid E, Bershteyn A, et al. HIV Treatment as Prevention: Systematic Comparison of Mathematical Models of the Potential Impact of Antiretroviral Therapy on HIV Incidence in South Africa. PLOS Medicine 2012,9:e1001245.

Ref16

Tanser F, Bärnighausen T, Grapsa E, Zaidi J, Newell M-L. High Coverage of ART Associated with Decline in Risk of HIV Acquisition in Rural KwaZulu-Natal, South Africa. Science 2013,339:966-971.

Ref17

Akullian A, Bershteyn A, Jewell B, Camlin CS. The Missing 27%. AIDS 2017.

Ref18(1,2,3,4)

World Health Organization (WHO), Global Health Observatory (GHO) data. http://www.who.int/gho/hiv/en/

Ref19(1,2)

The Global HIV/AIDS Epidemic, https://www.hiv.gov/hiv-basics/overview/data-and-trends/global-statistics

Ref20

World Health Organization (WHO) HIV/AIDS Fact Sheet http://www.who.int/mediacentre/factsheets/fs360/en/

Ref21(1,2,3,4)

UNAIDS, AIDS by the numbers http://www.unaids.org/en/resources/documents/2015/AIDS_by_the_numbers_2015

Ref22

Kim, S.B, et al., 2014. Mathematical Modeling of HIV Prevention Measures Including Pre-Exposure Prophylaxis on HIV Incidence in South Korea. PLOS One. March 24, 2014. https://doi.org/10.1371/journal.pone.0090080

Ref23

Eaton, J. W., et al. 2014. Health benefits, costs, and cost-effectiveness of earlier eligibility for adult antiretroviral therapy and expanded treatment coverage: a combined analysis of 12 mathematical models. The Lancet Global Health. V2. e23-234. http://www.thelancet.com/journals/langlo/article/PIIS2214-109X(13)70172-4/fulltext

Ref24

Meyer-Rath, G., Over, M., Klein, D., and Bershteyn, A., 2015. The Cost and Cost-Effectiveness of Alternative Strategies to Expand Treatment to HIV-Positive South Africans: Scale Economies and Outreach Costs - Working Paper 401. Center for Global Development. https://www.cgdev.org/publication/cost-and-cost-effectiveness-alternative-strategies-expand-treatment-hiv-positive-south

Ref25

Bershyteyn, A., Klein, D.J., and Eckhoff, P.A., 2016. AGe-targeted HIV treatment and primary prevention as a ‘ring fence’ to efficiently intterupt the age patterns of transmission in generalized epidemic settings in South Africa. International Health. 8(4): 277-285. https://doi.org/10.1093/inthealth/ihw010

Ref26

Klein, D., Eckhoff, P., and Bershteyn, A., 2015. Targeting HIV Services to Male Migrant Workers in Southern Africa Would Not Reverse Generalized HIV Epidemics. International Health. 7(2): 107-113. https://doi.org/10.1093/inthealth/ihv011

Ref27

Rivadeneira, P.S, et al., 2014. Mathematical Modeling of HIV Dynamics After Antiretroviral Therapy Initiation: A Review. Biores Open Access v.3(5): 233-241. doi: 10.1089/biores.2014.0024

Ref28

Ogunlaran, O.M., and Noutchie, C.O., 2016. Mathematical Model for an Effective Management of HIV Infection. BioMed Research International. Volume 2016, Article ID 217548, 6 pp. http://dx.doi.org/10.1155/2016/4217548

EMOD parameter reference

The configurable parameters described in this reference section determine the behavior of a particular simulation and interventions. The parameter descriptions are intended to guide you in correctly configuring simulations to match your disease scenario of interest.

This reference section contains only the parameters supported for use with the HIV simulation type. To see the parameters for a different simulation type, see the corresponding documentation.

These parameters include three major groups: parameters for the demographics file, parameters for the configuration file, and parameters for the campaign file.

If you would rather use a text file for parameter reference than this web documentation, you can also generate a schema with the EMOD executable (Eradication.exe) that defines all configuration and campaign parameters that can be used in a simulation, including names, data types, defaults, ranges, and short descriptions.

JSON formatting overview

All of these parameters are contained in JSON (JavaScript Object Notation) formatted files. JSON is a data format that is human-readable and easy for software to read and generate. It can be created and edited using a simple text editor.

JSON has two basic structures: a collection of key-value pairs or an ordered list of values (an array). These structures are within a JSON object, which is enclosed in a set of braces. You will notice that each of these files begins with a left brace ({) and ends with a right brace (}).

A value can be a string, number, Boolean, array, or an object. The campaign and data input files often use nested objects and arrays. See www.json.org for more information on JSON.

A few important details to call out when creating JSON files:

  • Add a comma after every key-value pair or array except for the last key-value pair in an array or object.

  • The keys (parameters) are case-sensitive. For example, “NodeID” is not the same as “NodeId”.

  • Decimals require a 0 (zero) before the decimal point.

  • EMOD does not support Booleans (“True”, “False”). Instead, EMOD use the integer 1 for “True” and 0 for “False”.

  • Every opening curly brace or square bracket ({ or [) requires a corresponding closing brace or bracket (} or ]).

The following is an example of a JSON formatted file.

{
    "A_Complex_Key": {
        "An_Array_with_a_Nested_Object_Value": [
            {
                "A_Simple_Key": "Value",
                "A_Simple_Array": [ "Value1", "Value2" ],
                "An_Array_with_Number_Values": [ 0.1, 0.2 ],
                "A_Nested_Object": {
                    "Another_Simple_Key": "Value",
                    "Nested_Arrays": [
                        [ 10, 0.1 ],
                        [ 0.1, 1 ]
                    ]
                }
            }
        ]
    }
}

JSON resources

The website https://jsonlint.com provides validation of JSON formatting. This can be very helpful in identifying missing commas, unbalanced curly braces, missing quotation marks, and other common JSON syntax errors. Another helpful site is http://jsondiff.com/, which highlights differences between two uploaded JSON files.

Demographics parameters

The parameters described in this reference section can be added to the JSON (JavaScript Object Notation) formatted demographics file to determine the demographics of the population within each geographic node in a simulation. For example, the number of individuals and the distribution for age, gender, immunity, risk, and mortality. These parameters work closely with the Population dynamics parameters in the configuration file, which are simulation-wide and generally control whether certain events, such as births or deaths, are enabled in a simulation.

Generally, you will download a demographics file and modify it to meet the needs of your simulation. Demographics files for several locations are available on the Institute for Disease Modeling (IDM) GitHub EMOD-InputData repository or you can use COmputational Modeling Platform Service (COMPS) to generate demographics and climate files for a particular region. By convention, these are named using the name of the region appended with “_demographics.json”, but you may name the file anything you like.

Additionally, you can use more than one demographics file, with one serving as the base layer and the one or more others acting as overlays that override the values in the base layer. This can be helpful if you want to experiment with different values in the overlay without modifying your base file. For more information, see Demographics file.

At least one demographics file is required for every simulation unless you set the parameter Enable_Demographics_Builtin to 1 (one) in the configuration file. This setting does not represent a real location and is generally only used for testing and validating code pathways rather than actual modeling of disease.

Demographics files are organized into four main sections: Metadata, NodeProperties, Defaults, and Nodes. The following example shows the skeletal format of a demographics file.

{
     "Metadata": {
          "DateCreated": "dateTime",
          "Tool": "scriptUsedToGenerate",
          "Author": "author",
          "IdReference": "Gridded world grump2.5arcmin",
          "NodeCount": 2
     },
     "NodeProperties": [
          {}
     ],
     "Defaults": {
          "NodeAttributes": {},
          "IndividualAttributes": {},
          "IndividualProperties": {},
          "Society": {}
     },
     "Nodes": [{
          "NodeID": 1,
          "NodeAttributes": {},
          "IndividualAttributes": {},
          "IndividualProperties": {},
          "Society": {}
     }, {
          "NodeID": 2,
          "NodeAttributes": {},
          "IndividualAttributes": {},
          "IndividualProperties": {},
          "Society": {}
     }]
}

All parameters except those in the Metadata and NodeProperties sections below can appear in either the Defaults section or the Nodes section of the demographics file. Parameters under Defaults will be applied to all nodes in the simulation. Parameters under Nodes will be applied to specific nodes, overriding the values in Defaults if they appear in both. Each node in the Nodes section is identified using a unique NodeID.

The tables below contain only parameters available when using the HIV simulation type.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Metadata

Metadata provides information about data provenance. IdReference is the only parameter used by EMOD, but you are encouraged to include information for your own reference. For example, author, date created, tool used, NodeCount and more are commonly included in the Metadata section. You can include any information you like here provided it is in valid JSON format. IDReference is used to connect the files together; the climate, migration, and demographics files all have IdReference so that there is some way to know that they go together (i.e. know about the same nodes).

If you generate input files using COMPS, the following IdReference values are possible and indicate how the NodeID values are generated:

Gridded world grump30arcsec

Nodes are approximately square regions defined by a 30-arc second grid and the NodeID values are generated from the latitude and longitude of the northwest corner.

Gridded world grump2.5arcmin

Nodes are approximately square regions defined by a 2.5-arc minute grid and the NodeID values are generated from the latitude and longitude of the northwest corner.

Gridded world grump1degree

Nodes are approximately square regions defined by a 1-degree grid and the NodeID values are generated from the latitude and longitude of the northwest corner.

The algorithm for encoding latitude and longitude into a NodeID is as follows:

unsigned int xpix = math.floor((lon + 180.0) / resolution)
unsigned int ypix = math.floor((lat + 90.0) / resolution)
unsigned int NodeID = (xpix << 16) + ypix + 1

This generates a NodeID that is a 4-byte unsigned integer; the first two bytes represent the longitude of the node and the second two bytes represent the latitude. To reserve 0 to be used as a null value, 1 is added to the NodeID as part of the final calculation.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Author

string

NA

NA

NA

The person who created the demographics file. Files generated by COMPS will include this value, but it is not used by EMOD simulations.

 
{
    "Metadata": {
        "DateCreated": "Sun Sep 25 23:19:55 2011",
        "Tool": "convertdemog.py",
        "Author": "jdoe",
        "IdReference": "Gridded world grump2.5arcmin",
        "NodeCount": 1
    }
}

DateCreated

string

NA

NA

NA

The date the demographics file was created. Files generated by COMPS will include this value, but it is not used by EMOD simulations.

 
{
    "Metadata": {
        "DateCreated": "09212017",
        "IdReference": "Gridded world grump2.5arcmin",
        "NodeCount": 23
    }
}

IdReference

string

NA

NA

NA

The identifier for a simulation; all input files (except configuration and campaign files) used in a simulation must have the same IdReference value. The value must be greater than 0. If the input files are generated using COMPS, this indicates the method used for generating the NodeID, the identifier used for each node in the simulation.

 
{
    "Metadata": {
        "IdReference": "Gridded world grump30arcsec"
    }
}

Metadata

JSON object

NA

NA

NA

The structure that contains the metadata for the demographics file.

 
{
    "Metadata": {
        "IdReference": "Gridded world grump30arcsec",
        "NodeCount": 20
    }
}

NodeCount

integer

1

Depends on available memory

NA

The number of nodes to expect in the input files. This parameter is required.

 
{
    "Metadata": {
        "NodeCount": 2
    }
}

Resolution

integer

NA

NA

NA

The spatial resolution of the demographics file. Files generated by COMPS will include this value, but it is not used by EMOD simulations.

 
{
    "Metadata": {
        "Resolution": 150
    }
}

Tool

string

NA

NA

NA

The software tool used to create the demographics file. Files generated by COMPS will include this value, but it is not used by EMOD simulations.

 
{
    "Metadata": {
        "Tool": "convertdemog.py",
        "Author": "jdoe",
        "IdReference": "Gridded world grump2.5arcmin",
        "Resolution": 150,
        "NodeCount": 1
    }
}
NodeProperties and IndividualProperties

Node properties and individual properties are set similarly and share many of the same parameters. Properties can be thought of as tags that are assigned to nodes or individuals and can then be used to either target interventions to nodes or individuals with certain properties (or prevent them from being targeted). For example, you could define individual properties for disease risk and then target an intervention to only those at high risk. Similarly, you could define properties for node accessibility and set lower intervention coverage for nodes that are difficult to access.

Individual properties are also used to simulate health care cascades. For example, you can disqualify an individual who would otherwise receive an intervention; such as treating a segment of the population with a second-line treatment but disqualifying those who haven’t already received the first-line treatment. Then you can change the property value after the treatment has been received.

The NodeProperties section is a top-level section at the same level as Defaults and Nodes that contains parameters that assign properties to nodes in a simulation. The IndividualProperties section is under either Defaults or Nodes and contains parameters that assign properties to individuals in a simulation.

Individual and node properties provides more guidance and Generic model scenarios provides some example scenarios that use properties.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Bin_Edges_In_Years

array

NA

NA

NA

An array of integers that represents the ages, in years, at which to demarcate the age groups for individuals. Used only with the Age_Bin property type. The first number must be 0, the last must be -1, and they must be listed in ascending order. Cannot be used with NodeProperties.

EMOD automatically create the individual property Age_Bin with values based on the bin edges using the format Age_Bin_Property_From_X_To_Y. These appear in the property reports and can be used to target campaign interventions using Property_Restrictions_Within_Node. See Targeting interventions to nodes or individuals for more information.

The following example creates three age groups: 0 to 5, older than 5 to 13, and older than 13 to the maximum age.

{
    "Defaults": {
        "IndividualProperties": [
            {
                "Property": "Age_Bin",
                "Age_Bin_Edges_In_Years": [
                    0,
                    5,
                    13,
                    -1
                ]
            }
        ]
    }
}

IndividualProperties

array of objects

NA

NA

NA

An array that contains parameters that add properties to individuals in a simulation. For example, you can define values for accessibility, age, geography, risk, and other properties and assign values to different individuals. alues.

 
{
    "Defaults": {
        "IndividualProperties": [
            {
                "Property": "InterventionStatus",
                "Values": [
                    "None",
                    "ARTStaging"
                ],
                "Initial_Distribution": [
                    1,
                    0
                ]
            },
            {
                "Property": "Risk",
                "Values": [
                    "High",
                    "Medium",
                    "Low"
                ],
                "Initial_Distribution": [
                    0.2,
                    0.5,
                    0.3
                ]
            }
        ]
    }
}

Initial_Distribution

array of floats

0

1

1

An array of floats that define the proportion of property values to assign to individuals or nodes at the beginning of the simulation and when new individuals are born. Their sum must equal 1 and the number of members in this array must match the number of members in Values. For Age_Bin property types, omit this parameter as the demographics file controls the age distribution.

 
{
    "NodeProperties": [
        {
            "Property": "InterventionStatus",
            "Values": [
                "NONE",
                "RECENT_SPRAY"
            ],
            "Initial_Distribution": [
                1.0,
                0.0
            ]
        }
    ]
}

{
    "Nodes": [
        {
            "NodeID": 25,
            "IndividualProperties": [
                {
                    "Initial_Distribution": [
                        0.2,
                        0.4,
                        0.4
                    ]
                }
            ]
        }
    ]
}

NodeProperties

array of objects

NA

NA

NA

An array that contains parameters that add properties to nodes in a simulation. Defined in the demographics file at the same level as Nodes and Defaults. For example, you can define values for intervention status, risk, and other properties and assign values to different nodes.

 
{
    "NodeProperties": [
        {
            "Property": "Place",
            "Values": [
                "RURAL",
                "URBAN"
            ],
            "Initial_Distribution": [
                0.85,
                0.15
            ]
        },
        {
            "Property": "InterventionStatus",
            "Values": [
                "NONE",
                "SPRAYED_A",
                "SPRAYED_B",
                "FENCE_AND_TRAP"
            ],
            "Initial_Distribution": [
                1,
                0,
                0,
                0
            ]
        }
    ],
    "Nodes": [
        {
            "NodeID": 1,
            "NodeAttributes": {
                "Latitude": 0,
                "Longitude": 0,
                "Altitude": 0,
                "Airport": 0,
                "Region": 1,
                "Seaport": 0,
                "InitialPopulation": 10000,
                "BirthRate": 5.48e-05,
                "NodePropertyValues": [
                    "Place:URBAN"
                ]
            }
        }
    ]
}

Property

enum

NA

NA

NA

The individual or node property type for which you will assign values to create groups. You can then update the property values assigned to individuals or nodes or target interventions to particular groups. Note that these types, with the exception of Age_Bin, are merely labels that do not affect the simulation unless specified to do so. Possible values are:

Age_Bin

Assign individuals to age bins. Use with Age_Bin_Edges_In_Years. Cannot be used with NodeProperties.

Accessibility

Tag individuals or nodes based on their accessibility.

Geographic

Tag individuals or nodes based on geographic characteristics.

HasActiveTB

Tag individuals or nodes based on active TB status. Typically used only with HIV ART staging interventions.

InterventionStatus

Tag individuals or nodes based on intervention status, so that receiving an intervention can affect how other interventions are distributed. Use with Disqualifying_Properties and New_Property_Value in the campaign file.

Place

Tag individuals or nodes based on place.

Risk

Tag individuals or nodes based on disease risk.

QualityofCare

Tag individuals or nodes based on the quality of medical care.

 
{
    "NodeProperties": [
        {
            "Property": "InterventionStatus",
            "Values": [
                "NONE",
                "RECENT_SPRAY"
            ],
            "Initial_Distribution": [
                1.0,
                0.0
            ]
        }
    ]
}

{
    "Defaults": {
        "IndividualProperties": [
            {
                "Property": "Age_Bin",
                "Age_Bin_Edges_In_Years": [
                    0,
                    6,
                    10,
                    20,
                    -1
                ]
            }
        ]
    }
}

TransmissionMatrix

JSON object

NA

NA

NA

An object that contains Route and Matrix parameters that define how to scale the base infectivity from individuals with one property value to individuals with another. Route can be set to “Contact” or “Environmental” and Matrix contains a WAIFW matrix of the disease transmission multipliers. The rows and columns are in the same order that the property values were defined in Value. The rows represent the infectious individuals (the “whom”); the columns represent the susceptible individuals (the “who”).

This implements the HINT feature, which is available only in the generic, environmental, and typhoid simulation types. For more information, see Property-based heterogeneous disease transmission (HINT). Enable_Heterogeneous_Intranode_Transmission in the configuration file must be set to 1 (see Infectivity and transmission parameters). Cannot be used with NodeProperties.

 
{
    "Defaults": {
        "IndividualProperties": [
            {
                "TransmissionMatrix": {
                    "Route": "Contact",
                    "Matrix": [
                        [
                            10,
                            0.1
                        ],
                        [
                            0.1,
                            1
                        ]
                    ]
                }
            }
        ]
    }
}

Values

array of strings

NA

NA

NA

An array of the user-defined values that can be assigned to individuals or nodes for this property. The order of the values corresponds to the order of the Initial_Distribution array.

You can have up to 125 values for the Geographic and InterventionStatus property types and up to 5 values for all other types. For Age_Bin property types, omit this parameter and use Age_Bin_Edges_In_Years instead.

 
{
    "NodeProperties": [
        {
            "Property": "InterventionStatus",
            "Values": [
                "NONE",
                "RECENT_SPRAY"
            ],
            "Initial_Distribution": [
                1.0,
                0.0
            ]
        }
    ]
}

{
    "Defaults": {
        "IndividualProperties": [
            {
                "Values": [
                    "Low",
                    "Medium",
                    "High"
                ]
            }
        ]
    }
}
NodeAttributes

The NodeAttributes section contains parameters that add or modify information regarding the location, migration, habitat, and population of node. Some NodeAttributes depend on values set in the configuration parameters.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Airport

boolean

0

1

0

Indicates whether or not the node has an airport for air migration from (not to) the node. If set to 1, Enable_Air_Migration in the configuration file must be set to 1 or migration will not occur (see Migration parameters). Primarily used to turn off migration in a particular node.

 
{
    "Defaults": {
        "NodeAttributes": {
            "Airport": 0
        }
    }
}

Altitude

float

-3.40282e+038

3.40282e+038

0

The altitude, in meters, for the node. Required, but only used when Climate_Model is set to CLIMATE_KOPPEN.

 
{
    "Defaults": {
        "NodeAttributes": {
            "Altitude": 250
        }
    }
}

BirthRate

double

0

1

0.00008715

The birth rate, in births per person per day. In the configuration file, Enable_Birth must be set to 1 and Birth_Rate_Dependence will affect how this rate is used (see Population dynamics parameters).

 
{
    "Nodes": [
        {
            "NodeID": 21,
            "NodeAttributes": {
                "BirthRate": 0.0001
            }
        }
    ]
}

InfectivityReservoirEndTime

float

InfectivityReservoirStartTime

3.40282e+038

3.40282e+038

The ending of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}

InfectivityReservoirSize

float

0

3.40282e+038

0

The quantity-per-timestep added to the total infectivity present in a node; it is equivalent to the expected number of additional infections in a node, per timestep. For example, if timestep is equal to a day, then setting InfectivityReservoirSize to a value of 0.1 would introduce an infection every 10 days from the exogenous reservoir. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}

InfectivityReservoirStartTime

float

0

3.40282e+038

0

The beginning of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).

 
{
    "NodeAttributes": {
        "InfectivityReservoirSize": 0.1,
        "InfectivityReservoirStartTime": 90,
        "InfectivityReservoirEndTime": 365
    }
}

InitialPopulation

integer

0

2147480000.0

1000

The number of people that will be populated into the node at the beginning of the simulation. You can scale this number using Base_Population_Scale_Factor in the configuration file (see Population dynamics parameters).

 
{
    "Nodes": [
        {
            "NodeID": 25,
            "NodeAttributes": {
                "InitialPopulation": 1000
            }
        }
    ]
}

Latitude

float

3.40282e+038

-3.40282e+038

-1

Latitude of the node in decimal degrees. This can be used for several things, including determining infectiousness by latitude and defining the size of grid cells.

 
{
    "Nodes": [
        {
            "NodeID": 25,
            "NodeAttributes": {
                "Latitude": 12.4,
                "Longitude": 9.35
            }
        }
    ]
}

Longitude

float

-3.40282e+38

3.40282e+38

-1

Longitude of the node in decimal degrees. This can be used for several things, including defining the size of grid cells.

 
{
    "Nodes": [
        {
            "NodeID": 254,
            "NodeAttributes": {
                "Latitude": 25.4,
                "Longitude": 9.1
            }
        }
    ]
}

NodeAttributes

JSON object

NA

NA

NA

The structure that contains parameters that add or modify information regarding the location, migration, habitat, and population of a simulation. Some NodeAttributes depend on values set in the configuration parameters.

 
{
    "Nodes": [
        {
            "NodeID": 1487548419,
            "NodeAttributes": {
                "Latitude": 12.4208,
                "Longitude": 9.15417
            }
        }
    ]
}

Region

boolean

0

1

0

Indicates whether or not the node has a road network for regional migration from (not to) the node. If set to 1, Enable_Regional_Migration in the configuration file must be set to 1 or migration will not occur (see Migration parameters). Primarily used to turn off migration in particular nodes.

 
{
    "Nodes": [
        {
            "NodeID": 12,
            "NodeAttributes": {
                "Region": 1
            }
        }
    ]
}

Seaport

boolean

0

1

0

Indicates whether or not the node is connected by sea migration from (not to) the node. If set to 1, Enable_Sea_Migration in the configuration file must be set to 1 or migration will not occur (see Migration parameters). Primarily used to turn off migration in particular nodes.

 
{
    "Nodes": [
        {
            "NodeID": 43,
            "NodeAttributes": {
                "Seaport": 1
            }
        }
    ]
}
IndividualAttributes

The IndividualAttributes section contains parameters that initialize the distribution of attributes across individuals, such as the age or immunity. An initial value for an individual is a randomly selected value from a given distribution. These distributions can be configured using a simple flag system of three parameters or a complex system of many more parameters. The following table contains the parameters that can be used with either distribution system.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

IndividualAttributes

JSON object

NA

NA

NA

The structure that contains parameters that add or modify the distribution of attributes across individuals in a simulation. For example, the age or immunity distribution. An initial value for an individual is a randomly selected value from a distribution. For example, if you use a uniform distribution to initialize age, the initial ages of individuals in the simulation will be evenly distributed between some minimum and maximum value. These distributions can be set using Simple distributions or Complex distributions.

 
{
    "Defaults": {
        "IndividualAttributes": {
            "AgeDistributionFlag": 0,
            "AgeDistribution1": 25550,
            "AgeDistribution2": 0
        }
    }
}

PercentageChildren

float

0

1

NA

The percentage of individuals in the node that are children. Set Minimum_Adult_Age_Years to determine the age at which individuals transition to adults.

 
{
    "Nodes": {
        "NodeID": 45,
        "IndividualAttributes": {
            "PercentageChildren": 0.7
        }
    }
}
Simple distributions

Simple distributions are defined by three parameters where one is a flag for the distribution type and the other two are used to further define the distribution. For example, if you set the age flag to a uniform distribution, the initial ages of individuals in the simulation will be evenly distributed between some minimum and maximum value as defined by the other two parameters.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

AgeDistribution1

float

-3.40282e+038

3.40282e+038

0.000118

The first value in the age distribution, the meaning of which depends upon the value set in AgeDistributionFlag. The table below shows the flag value and corresponding distribution value.

AgeDistributionFlag

AgeDistribution1

0

Age, in days, to assign to all individuals.

1

Minimum age, in days, for a uniform distribution.

2

Mean age, in days, for a Gaussian distribution.

3

Exponential decay rate.

4

Mean age, in days, for a Poisson distribution.

5

Mu (the mean of the natural log) for a log normal distribution.

6

Proportion of individuals in the second, user-defined age bin vs. the first age bin (1 day) for a bimodal distribution. Must be between 0 and 1.

7

Scale parameter for a Weibull distribution.

Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_SIMPLE (see Population dynamics parameters).

 
{
    "IndividualAttributes": {
        "AgeDistributionFlag": 0,
        "AgeDistribution1": 25550,
        "AgeDistribution2": 0
    }
}

AgeDistribution2

float

-3.40282e+038

3.40282e+038

0

The second value in the age distribution, the meaning of which depends upon the value set in AgeDistributionFlag. The table below shows the flag value and corresponding distribution value.

AgeDistributionFlag

AgeDistribution2

0

NA, set to 0.

1

Maximum age, in days, for a uniform distribution.

2

Standard deviation in age, in days, for a Gaussian distribution.

3

NA, set to 0.

4

NA, set to 0.

5

Sigma (the standard deviation of the natural log) for a log normal distribution.

6

The age, in days, of individuals in the second age bin for a bimodal distribution.

7

Shape parameter for a Weibull distribution.

Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_SIMPLE (see Population dynamics parameters).

 
{
    "IndividualAttributes": {
        "AgeDistributionFlag": 0,
        "AgeDistribution1": 25550,
        "AgeDistribution2": 0
    }
}

AgeDistributionFlag

integer

0

7

3

The type of distribution to use for age. Possible values are:

  • 0 (Constant, everyone in the population is the same age.)

  • 1 (Uniform, ages are randomly drawn between a minimum and maximum value.)

  • 2 (Gaussian)

  • 3 (Exponential)

  • 4 (Poisson)

  • 5 (Log normal)

  • 6 (Bimodal, non-continuous with some individuals 1 day old and others a user-defined age.)

  • 7 (Weibull)

Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_SIMPLE (see Population dynamics parameters).

 
{
    "IndividualAttributes": {
        "AgeDistributionFlag": 0,
        "AgeDistribution1": 25550,
        "AgeDistribution2": 0
    }
}

MigrationHeterogeneityDistribution1

float

-3.40282e+38

3.40282e+38

1

The first value in the migration heterogeneity distribution, the meaning of which depends upon the value set in MigrationHeterogeneityFlag. The table below shows the flag value and corresponding distribution value.

MigrationHeterogeneityDistributionFlag

MigrationHeterogeneityDistribution1

0

Migration heterogeneity value to assign.

1

Minimum migration heterogeneity for a uniform distribution.

2

Mean migration heterogeneity for a Gaussian distribution.

3

Exponential decay rate.

4

Mean migration heterogeneity for a Poisson distribution.

5

Mu (the mean of the natural log) for a log normal distribution.

6

Proportion of individuals in the second, user-defined migration heterogeneity bin vs. the first migration heterogeneity bin (value of 1 ) for a bimodal distribution. Must be between 0 and 1.

7

Scale parameter for a Weibull distribution.

Enable_Migration_Heterogeneity in the configuration file must be set to 1 (see Migration parameters).

 
{
    "IndividualAttributes": {
        "MigrationHeterogeneityDistributionFlag": 0,
        "MigrationHeterogeneityDistribution1": 1,
        "MigrationHeterogeneityDistribution2": 0
    }
}

MigrationHeterogeneityDistribution2

float

-3.40282e+038

3.40282e+038

0

The second value in the distribution, the meaning of which depends upon the value set in MigrationHeterogeneityDistributionFlag. The table below shows the flag value and corresponding distribution value.

MigrationHeterogeneityDistributionFlag

MigrationHeterogeneityDistribution2

0

NA, set to 0.

1

Maximum migration heterogeneity for a uniform distribution.

2

Standard deviation in migration heterogeneity for a Gaussian distribution.

3

NA, set to 0.

4

NA, set to 0.

5

Sigma (the standard deviation of the natural log) for a log normal distribution.

6

The migration heterogeniety of individuals in the second migration heterogeniety bin for a bimodal distribution.

7

Shape parameter for a Weibull distribution.

Enable_Migration_Heterogeneity in the configuration file must be set to 1 (see Migration parameters).

 
{
    "IndividualAttributes": {
        "MigrationHeterogeneityDistributionFlag": 0,
        "MigrationHeterogeneityDistribution1": 1,
        "MigrationHeterogeneityDistribution2": 0
    }
}

MigrationHeterogeneityDistributionFlag

integer

0

7

0

The type of distribution to use for migration heterogeneity. Possible values are:

  • 0 (Constant, everyone in the population has the same migration value.)

  • 1 (Uniform, migration values are randomly drawn between a minimum and maximum value.)

  • 2 (Gaussian)

  • 3 (Exponential)

  • 4 (Poisson)

  • 5 (Log normal)

  • 6 (Bimodal, non-continuous with some individuals with a migration heterogeniety of 1 and others a user-defined value.)

  • 7 (Weibull)

Enable_Migration_Heterogeneity in the configuration file must be set to 1 (see Migration parameters).

 
{
    "IndividualAttributes": {
        "MigrationHeterogeneityDistributionFlag": 0,
        "MigrationHeterogeneityDistribution1": 1,
        "MigrationHeterogeneityDistribution2": 0
    }
}

PrevalenceDistribution1

float

-3.40282e+038

3.40282e+038

1

The first value in the prevalence distribution, the meaning of which depends upon the value set in PrevalenceDistributionFlag. The table below shows the flag value and corresponding distribution value.

PrevalenceDistributionFlag

PrevalenceDistribution1

0

Prevalence value to assign.

1

Minimum prevalence for a uniform distribution.

2

Mean prevalence for a Gaussian distribution.

3

Exponential decay rate.

4

Mean prevalence for a Poisson distribution.

5

Mu (the mean of the natural log) for a log normal distribution.

6

Proportion of individuals in the second, user-defined prevalence bin vs. the first prevalence bin (value of 1) for a bimodal distribution. Must be between 0 and 1.

7

Scale parameter for a Weibull distribution.

 
{
    "IndividualAttributes": {
        "PrevalenceDistributionFlag": 0,
        "PrevalenceDistribution1": 0.0,
        "PrevalenceDistribution2": 0.0
    }
}

PrevalenceDistribution2

float

-3.40282e+038

3.40282e+038

0

The second value in the distribution, the meaning of which depends upon the value set in PrevalenceDistributionFlag. The table below shows the flag value and corresponding distribution value.

PrevalenceDistributionFlag

PrevalenceDistribution2

0

NA, set to 0.

1

Maximum prevalence for a uniform distribution.

2

Standard deviation in prevalence for a Gaussian distribution.

3

NA, set to 0.

4

NA, set to 0.

5

Sigma (the standard deviation of the natural log) for a log normal distribution.

6

The prevalence for individuals in the second prevalence bin for a bimodal distribution.

7

Shape parameter for a Weibull distribution.

 
{
    "IndividualAttributes": {
        "PrevalenceDistributionFlag": 0,
        "PrevalenceDistribution1": 0.0,
        "PrevalenceDistribution2": 0.0
    }
}

PrevalenceDistributionFlag

integer

0

7

0

The type of distribution to use for prevalence. Possible values are:

  • 0 (Constant, everyone in the population has the same prevalence.)

  • 1 (Uniform, prevalence is randomly drawn between a minimum and maximum value.)

  • 2 (Gaussian)

  • 3 (Exponential)

  • 4 (Poisson)

  • 5 (Log normal)

  • 6 (Bimodal, non-continuous with some individuals having a prevalence of 1 and others a user-defined prevalence.)

  • 7 (Weibull)

 
{
    "IndividualAttributes": {
        "PrevalenceDistributionFlag": 0,
        "PrevalenceDistribution1": 0.0,
        "PrevalenceDistribution2": 0.0
    }
}

RiskDistribution1

float

-3.40282e+038

3.40282e+038

0

The first value in the risk distribution, the meaning of which depends upon the value set in RiskDistributionFlag. The table below shows the flag value and corresponding distribution value.

RiskDistributionFlag

RiskDistribution1

0

Risk value to assign.

1

Minimum risk for a uniform distribution.

2

Mean risk for a Gaussian distribution.

3

Exponential decay rate.

4

Mean risk for a Poisson distribution.

5

Mu (the mean of the natural log) for a log normal distribution.

6

Proportion of individuals in the second, user-defined risk bin vs. the first risk bin (value of 1) for a bimodal distribution. Must be between 0 and 1.

7

Scale parameter for a Weibull distribution.

 
{
    "IndividualAttributes": {
        "RiskDistributionFlag": 0,
        "RiskDistribution1": 1,
        "RiskDistribution2": 0
    }
}

RiskDistribution2

float

-3.40282e+038

3.40282e+038

0

The second value in the distribution, the meaning of which depends upon the value set in RiskDistributionFlag. The table below shows the flag value and corresponding distribution value.

:header: RiskDistributionFlag, RiskDistribution2 :widths: 1, 3

0

NA, set to 0.

1

Maximum risk for a uniform distribution.

2

Standard deviation in risk for a Gaussian distribution.

3

NA, set to 0.

4

NA, set to 0.

5

Sigma (the standard deviation of the natural log) for a log normal distribution.

6

The risk of individuals in the second risk bin for a bimodal distribution.

7

Shape parameter for a Weibull distribution.

 
{
    "IndividualAttributes": {
        "RiskDistributionFlag": 0,
        "RiskDistribution1": 1,
        "RiskDistribution2": 0
    }
}

RiskDistributionFlag

integer

0

7

0

The type of distribution to use for risk. Possible values are:

  • 0 (Constant, everyone in the population has the same risk.)

  • 1 (Uniform, risk is randomly drawn between a minimum and maximum value.)

  • 2 (Gaussian)

  • 3 (Exponential)

  • 4 (Poisson)

  • 5 (Log normal)

  • 6 (Bimodal, non-continuous with some individuals with a risk of 1 and others a user-defined risk.)

  • 7 (Weibull)

Enable_Demographics_Risk must be set to 1 (see Population dynamics parameters).

 
{
    "IndividualAttributes": {
        "RiskDistributionFlag": 0,
        "RiskDistribution1": 1,
        "RiskDistribution2": 0
    }
}

SusceptibilityDistribution1

float

-3.40282e+038

3.40282e+038

0

The first value in the susceptibility distribution, the meaning of which depends upon the value set in SusceptibilityDistributionFlag. The table below shows the flag value and corresponding distribution value.

SusceptibilityDistributionFlag

SusceptibilityDistribution1

0

Probability of full susceptibility.

1

Minimum probability of susceptibility for a uniform distribution.

6

Proportion of individuals in the second, user-defined susceptibility bin vs. the first susceptibility bin (value of 1) for a bimodal distribution. Must be between 0 and 1.

In the configuration file, Enable_Immunity must be set to 1 and Susceptibility_Initialization_Distribution_Type must be set to DISTRIBUTION_SIMPLE (see Immunity parameters).

 
{
    "IndividualAttributes": {
        "SusceptibilityDistributionFlag": 0,
        "SusceptibilityDistribution1": 1,
        "SusceptibilityDistribution2": 0
    }
}

SusceptibilityDistribution2

float

-3.40282e+038

3.40282e+038

0

The second value in the susceptibility distribution, the meaning of which depends upon the value set in SusceptibilityDistributionFlag. The table below shows the flag value and corresponding distribution value.

SusceptibilityDistributionFlag

SusceptibilityDistribution2

0

NA, set to 0.

1

Maximum susceptibility for a uniform distribution.

6

The susceptibility values of individuals in the second susceptibility bin for a bimodal distribution.

In the configuration file, Enable_Immunity must be set to 1 and Susceptibility_Initialization_Distribution_Type must be set to DISTRIBUTION_SIMPLE (see Immunity parameters).

 
{
    "IndividualAttributes": {
        "SusceptibilityDistributionFlag": 0,
        "SusceptibilityDistribution1": 1,
        "SusceptibilityDistribution2": 0
    }
}

SusceptibilityDistributionFlag

integer

0

7

0

The type of distribution to use for determining an individual’s probability of full susceptibility. Possible values are:

  • 0 (Constant, everyone in the population has the same probability of susceptibility.)

  • 1 (Uniform, the probability of susceptibility is randomly drawn between a minimum and maximum value.)

  • 6 (Bimodal, non-continuous with some individuals’ probability of susceptibility at 1 and others with a user-defined probability.)

In the configuration file, Enable_Immunity must be set to 1 and Susceptibility_Initialization_Distribution_Type must be set to DISTRIBUTION_SIMPLE (see Immunity parameters).

 
{
    "IndividualAttributes": {
        "SusceptibilityDistributionFlag": 0,
        "SusceptibilityDistribution1": 1,
        "SusceptibilityDistribution2": 0
    }
}
Complex distributions

Complex distributions are more effort to configure, but are useful for representing real-world data where the distribution does not fit a standard. Individual attribute values are drawn from a piecewise linear distribution. The distribution is configured using arrays of axes (such as gender or age) and values at points along each of these axes. This allows you to have different distributions for different groups in the population.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

AgeDistribution

JSON object

NA

NA

NA

The structure defining a complex age distribution. Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX.

The following example shows at age distribution in which 25% of individuals are under age 5, 50% are between 5 and 20, and 25% are between 20 and 35.

{
    "IndividualAttributes": {
        "AgeDistribution": {
            "ResultUnits": "years",
            "ResultScaleFactor": 365,
            "ResultValues": [
                0,
                0.25,
                0.75,
                1
            ],
            "DistributionValues": [
                0,
                5,
                20,
                35
            ]
        }
    }
}

AxisNames

array of strings

NA

NA

NA

An array of the names used for each axis of a complex distribution. The list below shows the axis names to use (in the order given) for each of the distribution types:

MortalityDistribution

[“gender”, “age”] Death_Rate_Dependence in the configuration file must be set to NONDISEASE_MORTALITY_BY_AGE_AND_GENDER (see Mortality and survival parameters).

MortalityDistributionMale

[“age”, “year”] Death_Rate_Dependence must be set to NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER (see Mortality and survival parameters).

MortalityDistributionFemale

[“age”, “year”] Death_Rate_Dependence must be set to NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER (see Mortality and survival parameters).

FertilityDistribution

Two options are available:

  • [“urban”, “age”] Birth_Rate_Dependence in the configuratIon file must be set to INDIVIDUAL_PREGNANCIES_BY_URBAN_AND_AGE (see Population dynamics parameters).

  • [“age”, “year”] Birth_Rate_Dependence must be set to INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR (see Population dynamics parameters).

ImmunityDistribution

[“age”]

AgeDistribution

No axes.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    0
                ],
                [
                    0
                ]
            ]
        }
    }
}

AxisScaleFactors

array of floats

3.40282e+038

-3.40282e+038

1

A list of the scale factors used to convert axis units to data measurements in a complex distribution. For example, 365 to convert daily mortality to annual mortality. The array must contain one factor for each axis.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    0
                ],
                [
                    0
                ]
            ]
        }
    }
}

AxisUnits

array of strings

NA

NA

NA

An array that describes the scale factors used to convert the units for the axes into the units expected by EMOD. For example, when age is provided in years but must be scaled to days. EMOD does not use this value; it is only informational.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ]
        }
    }
}

DistributionValues

array of floats

0

1

1

An array of values between 0 and 1 listed in ascending order that defines a complex age distribution. Each value represents the proportion of the population below that age and the difference between two successive values is the proportion of the population in the age bin defined in ResultValues. Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX (see Population dynamics parameters).

The following example shows at age distribution in which 25% of individuals are under age 5, 50% are between 5 and 20, and 25% are between 20 and 35.

{
    "IndividualAttributes": {
        "AgeDistribution": {
            "ResultUnits": "years",
            "ResultScaleFactor": 365,
            "AxisScaleFactors": 1,
            "DistributionValues": [
                0,
                0.25,
                0.75,
                1
            ],
            "ResultValues": [
                0,
                5,
                20,
                35
            ]
        }
    }
}

FertilityDistribution

JSON object

NA

NA

NA

The distribution of the fertility rate in the population. Enable_Birth in the configuration file must be set to 1 (see Population dynamics parameters).

 
{
    "IndividualAttributes": {
        "FertilityDistribution": {
            "NumDistributionAxes": 2,
            "AxisNames": [
                "urban",
                "XXX"
            ],
            "AxisUnits": [
                "rural=0, urban=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                9
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0,
                    15,
                    20,
                    25,
                    30,
                    35,
                    40,
                    45,
                    49
                ]
            ],
            "ResultUnits": "annual births per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    0,
                    28.4,
                    190.3,
                    222.4,
                    155.4,
                    68,
                    21.9,
                    3.6,
                    0
                ],
                [
                    0,
                    28.4,
                    190.3,
                    222.4,
                    155.4,
                    68,
                    21.9,
                    3.6,
                    0
                ]
            ]
        }
    }
}

ImmunityDistribution

JSON object

NA

NA

NA

The structure defining a complex immunity distribution. Immunity_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX (see Immunity parameters).

 
{
    "IndividualAttributes": {
        "ImmunityDistribution": {
            "AxisNames": [
                "age"
            ],
            "AxisUnits": [
                "years"
            ],
            "AxisScaleFactors": [
                365
            ],
            "NumPopulationGroups": [
                1
            ],
            "PopulationGroups": [
                [
                    0
                ]
            ],
            "ResultScaleFactor": 3.6952,
            "ResultValues": [
                [
                    0
                ]
            ]
        }
    }
}

MortalityDistribution

JSON object

NA

NA

NA

The distribution of non-disease mortality for a population. Death_Rate_Dependence in the configuration file must be set to NONDISEASE_MORTALITY_BY_AGE_AND_GENDER or NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER (see Mortality and survival parameters).

Warning

Mortality is sampled every 30 days. To correctly attribute neonatal deaths to days 0-30, you must indicate that the threshold for the first age group in PopulationGroups is less than 30 days.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisScaleFactors": [
                1,
                1
            ],
            "NumDistributionAxes": 2,
            "NumPopulationGroups": [
                2,
                4
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0.0,
                    29.99,
                    365,
                    1826
                ]
            ],
            "ResultScaleFactor": 1,
            "ResultValues": [
                [
                    0.0016,
                    0.000107,
                    6.3e-05,
                    100.0
                ],
                [
                    0.0016,
                    0.000107,
                    6.3e-05,
                    100.0
                ]
            ]
        }
    }
}

NumDistributionAxes

integer

1

NA

NA

The number of axes to use for a complex distribution. EMOD does not use this value; it is only informational.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "NumDistributionAxes": 2,
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisScaleFactors": [
                1,
                365
            ]
        }
    }
}

NumPopulationGroups

array of integers

NA

NA

NA

An array of population groupings for each independent variable for a complex distribution. This variable defines the number of columns for each row in the population group table. The number of values in the array is often two, representing the values for gender and number of age bins. EMOD does not use this value; it is only informational.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    0
                ],
                [
                    0
                ]
            ]
        }
    }
}

PopulationGroups

matrix of integers

NA

NA

NA

An array in which each row represents one of the distribution axes and contains the values that the independent variable can take. The values must be listed in ascending order and each defines the left edge of the bin.

Warning

Mortality is sampled every 30 days. To correctly attribute neonatal deaths to days 0-30, you must indicate that the threshold for the first age group in PopulationGroups is less than 30 days.

The following example configures relatively high infant mortality and lower mortality at ages 10 and 40, with everyone dead by age 120.

{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0,
                    10,
                    40,
                    120
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    51.6,
                    3.7,
                    5.3,
                    1000
                ],
                [
                    60.1,
                    4.1,
                    4.8,
                    1000
                ]
            ]
        }
    }
}

ResultScaleFactor

float

-3.40282e+038

3.40282e+038

1

The scale factor used to convert ResultUnits to number of births, deaths, or another variable per individual per day.

 
{
    "IndividualAttributes": {
        "AgeDistribution": {
            "AxisScaleFactors": 1,
            "DistributionValues": [
                0.99,
                1.0
            ],
            "ResultScaleFactor": 365,
            "ResultUnits": "years",
            "ResultValues": [
                0.0027,
                0.0027
            ]
        }
    }
}

ResultUnits

string

NA

NA

NA

A string that indicates the units used for the ResultValues parameter of a complex distribution. EMOD does not use this value; it is only informational. The values here are scaled by the value in ResultScaleFactor before being passed to EMOD as a daily rate.

 
{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    0
                ],
                [
                    0
                ]
            ]
        }
    }
}

ResultValues

array of floats

NA

NA

NA

An array in which each row represents one of the distribution axes and contains the dependent variable values. The units are configurable; the values are scaled by the value in ResultScaleFactor before being passed to EMOD in units of days.

For age distributions, it lists in ascending order the ages at which to bin the population. The corresponding values in DistributionValues represent the proportion of the population that is below that age. If the first member of the array is non-zero, the first bin is defined as those with that exact value (EMOD does not assume the bins start at zero).

For all other distributions, an array in which each row represents the values for a combination of axes. For example, a mortality distribution that includes both gender and age axes will have a row for males and a row for females that each contain the mortality rate at various ages set in PopulationGroups.

The following example shows an age distribution in which 10% of individuals are newborn, 25% are under age 5, 50% are between 5 and 20, and 25% are between 20 and 35.

{
    "IndividualAttributes": {
        "AgeDistribution": {
            "DistributionValues": [
                0.1,
                0.25,
                0.75,
                1
            ],
            "ResultValues": [
                0,
                5,
                20,
                35
            ]
        }
    }
}

The following example configures relatively high infant mortality and lower mortality at ages 10 and 40, with everyone dead by age 120.

{
    "IndividualAttributes": {
        "MortalityDistribution": {
            "AxisNames": [
                "gender",
                "age"
            ],
            "AxisUnits": [
                "male=0,female=1",
                "years"
            ],
            "AxisScaleFactors": [
                1,
                365
            ],
            "NumPopulationGroups": [
                2,
                1
            ],
            "PopulationGroups": [
                [
                    0,
                    1
                ],
                [
                    0,
                    10,
                    40,
                    120
                ]
            ],
            "ResultUnits": "annual deaths per 1000 individuals",
            "ResultScaleFactor": 2.739726027397e-06,
            "ResultValues": [
                [
                    51.6,
                    3.7,
                    5.3,
                    1000
                ],
                [
                    60.1,
                    4.1,
                    4.8,
                    1000
                ]
            ]
        }
    }
}

SusceptibilityDistribution

JSON object

NA

NA

NA

The structure defining a complex immunity/susceptibility distribution. Susceptibility_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX (see Immunity parameters).

 
{
    "IndividualAttributes": {
        "SusceptibilityDistribution": {
            "AxisNames": [
                "age"
            ],
            "AxisScaleFactors": [
                365
            ],
            "AxisUnits": [
                "years"
            ],
            "NumPopulationGroups": [
                1
            ],
            "PopulationGroups": [
                [
                    0
                ]
            ],
            "ResultScaleFactor": 3.6952,
            "ResultValues": [
                [
                    0
                ]
            ]
        }
    }
}
Society

The Society section defines the behavioral-based parameters of a relationship type in the STI and HIV models, such as rates of partnership formation, partner preference, relationship duration, or concurrent partnerships. It must contain the four sets of relationship type parameters and the Concurrency_Configuration section. Note that the name used for each relationship type is only a guide; EMOD does not include specific logic for each type and the settings for each depend only upon the parameters you provide.

The section for each relationship type must include the Relationship_Parameters, Pair_Formation_Parameters, and Concurrency_Parameters sections. These sections define the settings for the specific relationship type they are nested under.

The Concurrency_Configuration section defines how the simultaneous relationship parameters are used across all relationship types.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

COMMERCIAL

JSON object

NA

NA

NA

The structure that defines basic relationship, pair formation, and concurrency parameters for transactional relationships involving commercial sex work (CSW).

 
{
    "Society": {
        "COMMERCIAL": {
            "Relationship_Parameters": {
                "Condom_Usage_Probability": {
                    "Min": 0.02,
                    "Max": 0.65,
                    "Mid": 2000,
                    "Rate": 1.5
                }
            },
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.05
            },
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 20,
                    "Max_Simultaneous_Relationships_Male": 20
                }
            }
        }
    }
}

Concurrency_Configuration

JSON object

NA

NA

NA

The structure that determines how concurrent relationships are formed, for all relationship types. To apply to all individuals regardless of individual property values, nest parameters under NONE. To apply only to individuals with certain property values, nest parameters under the property value.

The following example sets extra-relational flags independently to everyone regardless of individual properties.

{
    "Society": {
        "Concurrency_Configuration": {
            "Probability_Person_Is_Behavioral_Super_Spreader": 0,
            "Individual_Property_Name": "NONE",
            "NONE": {
                "Extra_Relational_Flag_Type": "Independent"
            }
        }
    }
}

The following example sets different extra-relational flag types to low-risk and high-risk groups.

{
    "Society": {
        "Concurrency_Configuration": {
            "Individual_Property_Name": "Risk",
            "LOW": {
                "Extra_Relational_Flag_Type": "Independent"
            },
            "HIGH": {
                "Extra_Relational_Flag_Type": "Correlated"
            }
        }
    }
}

INFORMAL

JSON object

NA

NA

NA

The structure that defines basic relationship, pair formation, and concurrency parameters for longer-term non-marital relationships.

 
{
    "Society": {
        "INFORMAL": {
            "Relationship_Parameters": {
                "Condom_Usage_Probability": {
                    "Min": 0.0125,
                    "Max": 0.45,
                    "Mid": 2000,
                    "Rate": 1.5
                }
            },
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.01
            },
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3
                }
            }
        }
    }
}

MARITAL

JSON object

NA

NA

NA

The structure that defines basic relationship, pair formation, and concurrency parameters for marital relationships.

 
{
    "Society": {
        "MARITAL": {
            "Relationship_Parameters": {
                "Condom_Usage_Probability": {
                    "Min": 0.002,
                    "Max": 0.05,
                    "Mid": 2000,
                    "Rate": 1.5
                }
            },
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.006
            },
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 1,
                    "Max_Simultaneous_Relationships_Male": 1
                }
            }
        }
    }
}

Pair_Formation_Parameters

JSON object

NA

NA

NA

Structure that defines all relationship formation parameters for the relationship type specified.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Extra_Relational_Rate_Ratio_Male": 4,
                "Extra_Relational_Rate_Ratio_Female": 2
            }
        }
    }
}

Society

JSON object

NA

NA

NA

The structure that defines the behavioral-based parameters of a relationship type. Under this structure, include the following and assign JSON objects to each:

Concurrency_Configuration

Defines how the simultaneous relationship parameters are used across all relationship types.

TRANSITORY

All parameters for brief relationships lasting one night, weekend, or week.

INFORMAL

All parameters for longer-term non-marital relationships.

MARITAL

All parameters for marital relationships.

COMMERCIAL

All parameters for transactional relationships involving commercial sex work (CSW).

 
{
    "Society": {
        "Concurrency_Configuration": {
            "NONE": {
                "Extra_Relational_Flag_Type": "Correlated",
                "Correlated_Relationship_Type_Order": [
                    "TRANSITORY",
                    "INFORMAL",
                    "MARITAL",
                    "COMMERCIAL"
                ]
            }
        },
        "MARITAL": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "INDIVIDUAL_PROPERTY",
                    "Property_Name": "Risk",
                    "Axes": [
                        "LOW",
                        "HIGH"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.8275185967686474,
                            0.17248140323135264
                        ],
                        [
                            0.17248140323135264,
                            0.8275185967686474
                        ]
                    ]
                }
            }
        },
        "INFORMAL": {},
        "TRANSITORY": {},
        "COMMERCIAL": {}
    }
}

TRANSITORY

JSON object

NA

NA

NA

The structure that defines basic relationship, pair formation, and concurrency parameters for brief relationships lasting one night, weekend, or week.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Condom_Usage_Probability": {
                    "Min": 0.0125,
                    "Max": 0.45,
                    "Mid": 2000,
                    "Rate": 1.5
                }
            },
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.01
            },
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3
                }
            }
        }
    }
}
Concurrency_Configuration

The Concurrency_Configuration section is at the same level as each relationship type section and defines how the simultaneous relationship parameters are used across all relationship types. For example, how flags that allow an individual to seek out different types of extra-relational partnerships are distributed.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Correlated_Relationship_Type_Order

array of strings

NA

NA

NA

The relationship types listed in order of the correlated probabilities. The array must contain all relationship types and Extra_Relational_Flag_Type must be set to Correlated.

 
{
    "Society": {
        "Concurrency_Configuration": {
            "NONE": {
                "Extra_Relational_Flag_Type": "Correlated",
                "Correlated_Relationship_Type_Order": [
                    "TRANSITORY",
                    "INFORMAL",
                    "MARITAL",
                    "COMMERCIAL"
                ]
            }
        }
    }
}

Extra_Relational_Flag_Type

enum

NA

NA

Independent

The manner in which extra-relational flags are distributed. Individuals cannot seek additional concurrent relationships unless they have a flag for the relationship type they are currently in. Possible values are Correlated or Independent.

When independent flags are enabled, all flags are distributed randomly and an individual is unlikely to receive all extra-relational flags. When correlated flags are enabled, flags are distributed for each relationship type in the order listed, with the first flags distributed randomly and each subsequent flag distributed only among individuals who have the prior flag.

The probability of receiving a flag is defined in Prob_Extra_Relationship_Male and Prob_Extra_Relationship_Female in Concurrency_Parameters.

In the following example, the extra-transitory flag is randomly distributed, the extra-informal flag is provided only to those who possess the extra-transitory flag, and so on.

{
    "Society": {
        "Concurrency_Configuration": {
            "NONE": {
                "Extra_Relational_Flag_Type": "Correlated",
                "Correlated_Relationship_Type_Order": [
                    "TRANSITORY",
                    "INFORMAL",
                    "MARITAL",
                    "COMMERCIAL"
                ]
            }
        }
    }
}

Individual_Property_Name

string

NA

NA

NA

The individual property used to create groups of people for configuring relationship concurrency settings. The property name must be defined in the IndividualProperties section. If the concurrency settings do not vary based on individual properties, set to NONE.

The following example configures different concurrency settings for high and low risk individuals.

{
    "Society": {
        "Concurrency_Configuration": {
            "Probability_Person_Is_Behavioral_Super_Spreader": 0,
            "Individual_Property_Name": "Risk",
            "LOW": {
                "Extra_Relational_Flag_Type": "Independent"
            },
            "HIGH": {
                "Extra_Relational_Flag_Type": "Correlated"
            }
        }
    }
}

The following example configures the same concurrency settings for all individuals.

{
    "Society": {
        "Concurrency_Configuration": {
            "Individual_Property_Name": "NONE",
            "NONE": {
                "Max_Simultaneous_Relationships_Female": 4,
                "Max_Simultaneous_Relationships_Male": 4,
                "Prob_Extra_Relationship_Female": 1,
                "Prob_Extra_Relationship_Male": 1
            }
        }
    }
}

Probability_Person_Is_Behavioral_Super_Spreader

float

0

1

0.001

The probability that an individual is a behavioral super spreader, where they are allowed multiple relationships of all types.

 
{
    "Social": {
        "Concurrency_Configuration": {
            "Probability_Person_Is_Behavioral_Super_Spreader": 0.25,
            "Individual_Property_Name": "NONE",
            "NONE": {
                "Extra_Relational_Flag_Type": "Independent"
            }
        }
    }
}
Relationship_Parameters

The Relationship_Parameters section defines basic attributes such as relationship duration, what happens if one member of a relationship migrates, and condom usage.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Coital_Act_Rate

float

FLT_EPSILON

20

0.33

The probability of a coital act occurring at each time step.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Coital_Act_Rate": 1
            }
        }
    }
}

Condom_Usage_Probability

JSON object

NA

NA

NA

The structure that determines the probability of condom usage over time in a relationship type. The probability follows a sigmoidal curve, as defined by the following parameters:

Min

The minimum asymptote (0 to 1, default 1).

Max

The maximum asymptote (0 to 1, default 1).

Mid

The year of the inflection point (0 to 3.40282e+038, default 2000).

Rate

The rate proportional to the slope at the inflection point (-100 to 100, default is 1).

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Condom_Usage_Probability": {
                    "Min": 0.0125,
                    "Max": 0.3,
                    "Mid": 2001,
                    "Rate": 1.5
                }
            }
        }
    }
}

Duration_Weibull_Heterogeneity

float

0

100

1

Inverse of the Weibull shape (1/kappa) parameter of relationship duration in years.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Duration_Weibull_Heterogeneity": 0.1,
                "Duration_Weibull_Scale": 1051025.709
            }
        }
    }
}

Duration_Weibull_Scale

float

0

3.40282e+038

1

Weibull scale parameter of relationship duration in years.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Duration_Weibull_Heterogeneity": 0.1,
                "Duration_Weibull_Scale": 1051025.709
            }
        }
    }
}

Max

float

0

1

1

The maximum asymptote (unit of probability) for sigmoidal curve. This parameter is included in the sigmoid utility class, which is currently used with the HIV sim type for the Formation_Rate_Sigmoid and Condom_Usage_Probability parameters.

 
{
    "Max": 0.3,
    "Mid": 2019,
    "Min": 0.0125,
    "Rate": 1.5
}

Mid

float

0

3.40282e+038

2000

The year of the inflection point for sigmoidal curve. This parameter is included in the sigmoid utility class, which is currently used with the HIV sim type for the Formation_Rate_Sigmoid and Condom_Usage_Probability parameters.

 
{
    "Min": 0.0125,
    "Max": 0.3,
    "Mid": 2019,
    "Rate": 1.5
}

Migration_Actions

array of enums

NA

NA

NA

A list of what relationship action to take when one member of the relationship migrates to another node. The order in which they are listed corresponds to the probability values in Migration_Actions_Distributions. Migration_Model in the configuration file must be set to FIXED_RATE_MIGRATION. Possible values are:

Terminate

Relationship is stopped. The individual’s relationship count is decremented so they can enter new relationships.

Pause

Relationship is put on hold. The couple is not in the same node so they cannot consummate their relationship, but the individual’s relationship count is not decremented since they are still in the relationship. The relationship can resume if both partners are in the same node, which need not be their home node. Relationship duration timers continue and relationship could terminate while paused.

Migrate

Partners in the relationship migrate simultaneously and continue the relationship. Person migrating tells their partner to cancel all of their relationships and migrate during the current time step. This avoids a cascade of people migration.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Migration_Actions": [
                    "TERMINATE",
                    "PAUSE",
                    "MIGRATE"
                ],
                "Migration_Actions_Distribution": [
                    0.7,
                    0.2,
                    0.1
                ]
            }
        }
    }
}

Migration_Actions_Distribution

array of floats

0

1

NA

A list of the proportion of relationships that take a given action when one member of the relationship migrates. The sum of all values must be 1 and the order of the list corresponds to the order in Migration_Actions. Migration_Model in the configuration file must be set to FIXED_RATE_MIGRATION.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Migration_Actions": [
                    "TERMINATE",
                    "PAUSE",
                    "MIGRATE"
                ],
                "Migration_Actions_Distribution": [
                    0.7,
                    0.2,
                    0.1
                ]
            }
        }
    }
}

Min

float

0

1

1

The minimum asymptote (unit of probability) for sigmoidal curve. This parameter is included in the sigmoid utility class, which is currently used with the HIV sim type for the Formation_Rate_Sigmoid and Condom_Usage_Probability parameters.

 
{
    "Min": 0.0125,
    "Max": 0.3,
    "Mid": 2019,
    "Rate": 1.5
}

Rate

float

-100

100

1

The rate (probability/year) proportional to the slope at the inflection point of sigmoidal curve. This parameter is included in the sigmoid utility class, which is currently used with the HIV sim type for the Formation_Rate_Sigmoid and Condom_Usage_Probability parameters.

 
{
    "Max": 0.3,
    "Mid": 2019,
    "Min": 0.0125,
    "Rate": 1.5
}

Relationship_Parameters

JSON object

NA

NA

NA

The structure that determines basic aspects of the relationship, such as duration, condom usage, or how to handle migration.

 
{
    "Society": {
        "TRANSITORY": {
            "Relationship_Parameters": {
                "Migration_Actions": [
                    "TERMINATE",
                    "PAUSE",
                    "MIGRATE"
                ],
                "Migration_Actions_Distribution": [
                    0.7,
                    0.2,
                    0.1
                ]
            }
        }
    }
}
Pair_Formation_Parameters

The Pair_Formation_Parameters section defines the rate at which new relationships are formed and partnership preference using the main pair forming algorithm that finds potential partners based on their age and the Joint_Probabilities matrix.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_of_First_Bin_Edge_Female

integer

0

100

1

The maximum age for the first age bin when dividing the female population into age bins for pair formation.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Number_Age_Bins_Male": 25,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 10,
                "Age_of_First_Bin_Edge_Female": 20
            }
        }
    }
}

Age_of_First_Bin_Edge_Male

integer

0

100

1

The maximum age for the first age bin when dividing the male population into age bins for pair formation.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Number_Age_Bins_Male": 25,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 10,
                "Age_of_First_Bin_Edge_Female": 20
            }
        }
    }
}

Assortivity

JSON object

NA

NA

NA

The object that defines how people will preferentially form pairs based on their membership in different groups.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "INDIVIDUAL_PROPERTY",
                    "Property_Name": "Risk",
                    "Axes": [
                        "LOW",
                        "HIGH"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.8275185967686474,
                            0.17248140323135264
                        ],
                        [
                            0.17248140323135264,
                            0.8275185967686474
                        ]
                    ]
                }
            }
        }
    }
}

Extra_Relational_Rate_Ratio_Female

integer

1

3.40282e+038

1

For women, the rate ratio for having extra-relational sex for this relationship type, where the ratio is the event over the period of time defined in Update_Period.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Update_Period": 7.0,
                "Extra_Relational_Rate_Ratio_Male": 4,
                "Extra_Relational_Rate_Ratio_Female": 2
            }
        }
    }
}

Extra_Relational_Rate_Ratio_Male

integer

1

3.40282e+038

1

For males, the rate ratio for having extra-relational sex for this relationship type, where the ratio is the event over the period of time defined in Update_Period.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Update_Period": 7.0,
                "Extra_Relational_Rate_Ratio_Male": 4,
                "Extra_Relational_Rate_Ratio_Female": 2
            }
        }
    }
}

Formation_Rate_Constant

float

0

1

0.001

If Formation_Rate_Type is set to CONSTANT, the number of new relationships per day for this relationship type.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0013,
                "Update_Period": 7.0,
                "Extra_Relational_Rate_Ratio_Male": 5,
                "Extra_Relational_Rate_Ratio_Female": 2
            }
        }
    }
}

Formation_Rate_Interpolated_Values

JSON object

NA

NA

NA

The structure that contains two arrays of floats specifying Times and Values arrays that will be interpolated to provide the formation rate when Formation_Rate_Type is set to INTERPOLATED_VALUES. The years listed in Times must be in ascending order; the first year must be prior to the current year and if the last year is prior to the current year, the last value in Values will be used for the formation rate.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Type": "INTERPOLATED_VALUES",
                "Formation_Rate_Interpolated_Values": {
                    "Times": [
                        1980,
                        2000,
                        2020
                    ],
                    "Values": [
                        0.2,
                        0.8,
                        0.4
                    ]
                }
            }
        }
    }
}

Formation_Rate_Sigmoid

JSON object

NA

NA

NA

The structure that determines the shape of the sigmoidal curve for pair formation when Formation_Rate_Type is set to SIGMOID_VARIABLE_WIDTH_HEIGHT. Include the following parameters:

Min

The minimum asymptote (0 to 1, default 1).

Max

The maximum asymptote (0 to 1, default 1).

Mid

The year of the inflection point (0 to 100000, default 2000).

Rate

The rate (proportional to the slope by a factor of 4) at the inflection point (-100 to 100, default 1).

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Type": "SIGMOID_VARIABLE_WIDTH_HEIGHT",
                "Formation_Rate_Sigmoid": {
                    "Min": 0.6,
                    "Max": 0.9,
                    "Mid": 2010,
                    "Rate": 3
                }
            }
        }
    }
}

Formation_Rate_Type

enum

NA

NA

CONSTANT

The type of functional form that describes that pair formation rate. Possible values are:

CONSTANT

The rate is a constant value.

SIGMOID_VARIABLE_WIDTH_HEIGHT

The rate is a sigmoidal curve.

INTERPOLATED_VALUES

The rate is interpolated between a set of supplied values.

 
{
    "Society": {
        "MARITAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Type": "CONSTANT",
                "Formation_Rate_Constant": 0.002739726
            }
        }
    }
}

Joint_Probabilities

matrix of floats

0

3.40282e+038,

0

The relative preference of members of one age bin to form relationships with members of another age bin. The columns represent female bins and rows represent male bins.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0027398,
                "Update_Period": 7.0,
                "Number_Age_Bins_Male": 2,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 50,
                "Age_of_First_Bin_Edge_Female": 50,
                "Years_Between_Bin_Edges_Male": 35,
                "Years_Between_Bin_Edges_Female": 35,
                "Joint_Probabilities": [
                    [
                        0,
                        1
                    ],
                    [
                        1,
                        0
                    ]
                ]
            }
        }
    }
}

Number_Age_Bins_Female

integer

1

1000

1

The number of age bins to divide the female population into for pair formation.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0027398,
                "Update_Period": 7.0,
                "Number_Age_Bins_Male": 2,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 50,
                "Age_of_First_Bin_Edge_Female": 50,
                "Years_Between_Bin_Edges_Male": 35,
                "Years_Between_Bin_Edges_Female": 35,
                "Joint_Probabilities": [
                    [
                        0,
                        1
                    ],
                    [
                        1,
                        0
                    ]
                ]
            }
        }
    }
}

Number_Age_Bins_Male

integer

1

1000

1

The number of age bins to divide the male population into for pair formation.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0027398,
                "Update_Period": 7.0,
                "Number_Age_Bins_Male": 2,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 50,
                "Age_of_First_Bin_Edge_Female": 50,
                "Years_Between_Bin_Edges_Male": 35,
                "Years_Between_Bin_Edges_Female": 35,
                "Joint_Probabilities": [
                    [
                        0,
                        1
                    ],
                    [
                        1,
                        0
                    ]
                ]
            }
        }
    }
}

Update_Period

float

0

3.40282e+38

0

The period, in days, to wait before an individual is eligible to seek out new relationships.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0013,
                "Update_Period": 7.0,
                "Extra_Relational_Rate_Ratio_Male": 5,
                "Extra_Relational_Rate_Ratio_Female": 2
            }
        }
    }
}

Years_Between_Bin_Edges_Female

float

0.1

100

1

For the female population, the number of years covered in each age bin.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0027398,
                "Update_Period": 7.0,
                "Number_Age_Bins_Male": 2,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 50,
                "Age_of_First_Bin_Edge_Female": 50,
                "Years_Between_Bin_Edges_Male": 35,
                "Years_Between_Bin_Edges_Female": 35,
                "Joint_Probabilities": [
                    [
                        0,
                        1
                    ],
                    [
                        1,
                        0
                    ]
                ]
            }
        }
    }
}

Years_Between_Bin_Edges_Male

integer

0.1

100

1

For the male population, the number of years covered in each age bin.

 
{
    "Society": {
        "INFORMAL": {
            "Pair_Formation_Parameters": {
                "Formation_Rate_Constant": 0.0027398,
                "Update_Period": 7.0,
                "Number_Age_Bins_Male": 2,
                "Number_Age_Bins_Female": 2,
                "Age_of_First_Bin_Edge_Male": 50,
                "Age_of_First_Bin_Edge_Female": 50,
                "Years_Between_Bin_Edges_Male": 35,
                "Years_Between_Bin_Edges_Female": 35,
                "Joint_Probabilities": [
                    [
                        0,
                        1
                    ],
                    [
                        1,
                        0
                    ]
                ]
            }
        }
    }
}
Assortivity

The Assortivity section refines who partners with whom. After the main pair forming algorithm reduces the set of potential partners to a subset based on age, Assortivity allows for selection based on other criteria.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Axes

array of strings

NA

NA

NA

The axes defined in Group to use for the weighting matrix for pair formation. The order of the array defines the order of the weighting matrix.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "INDIVIDUAL_PROPERTY",
                    "Property_Name": "Risk",
                    "Axes": [
                        "LOW",
                        "HIGH"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.8275185967686474,
                            0.17248140323135264
                        ],
                        [
                            0.17248140323135264,
                            0.8275185967686474
                        ]
                    ]
                }
            }
        }
    }
}

Group

enum

NA

NA

NO_GROUP

The group that individuals may belong to that is used for weighting assortivity for pair formation. Possible values are:

NO_GROUP

Pair with the first person on the list (no axes).

STI_INFECTION_STATUS

Pair based on STI status (TRUE/FALSE axes).

INDIVIDUAL_PROPERTY

Pair based on individual properties (axes are the individual property values).

STI_COINFECTION_STATUS

Pair based on STI co-infection status (TRUE/FALSE axes).

HIV_INFECTION_STATUS

Pair based on HIV infection status, as per infectivity (TRUE/FALSE axes).

HIV_TESTED_POSITIVE_STATUS

Pair based on HIV infection status, as per test results (TRUE/FALSE axes).

HIV_RECEIVED_RESULTS_STATUS

Pair with someone who has received similar HIV test results (UNKNOWN, POSITIVE, NEGATIVE axes).

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "INDIVIDUAL_PROPERTY",
                    "Property_Name": "Risk",
                    "Axes": [
                        "LOW",
                        "HIGH"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.8275185967686474,
                            0.17248140323135264
                        ],
                        [
                            0.17248140323135264,
                            0.8275185967686474
                        ]
                    ]
                }
            }
        }
    }
}

Property_Name

string

NA

NA

NA

If Group is set to INDIVIDUAL_PROPERTY, the name of the individual property as defined in the IndividualProperties section.

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "INDIVIDUAL_PROPERTY",
                    "Property_Name": "Risk",
                    "Axes": [
                        "LOW",
                        "HIGH"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.8275185967686474,
                            0.17248140323135264
                        ],
                        [
                            0.17248140323135264,
                            0.8275185967686474
                        ]
                    ]
                }
            }
        }
    }
}

Start_Year

float

1900

2200

1900

The year to start using the assortivity weighting matrix. The value must be prior to the current year or Group will be set to NO_GROUP. Used only when the Group value is one of the following:

  • STI_COINFECTION_STATUS

  • HIV_INFECTION_STATUS

  • HIV_TESTED_POSITIVE_STATUS

  • HIV_RECEIVED_RESULTS_STATUS

 
{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "HIV_INFECTION_STATUS",
                    "Start_Year": 1990,
                    "Axes": [
                        "True",
                        "FALSE"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.75,
                            0.25
                        ],
                        [
                            0.4,
                            0.6
                        ]
                    ]
                }
            }
        }
    }
}

Weighting_Matrix_RowMale_ColumnFemale

matrix of floats

0

1

0

The weights to apply to pair formation rates for individuals belonging to the groups defined in Axes. Rows are indexed by the male attribute and columns by the female attribute as defined in Axes. A single row or column cannot be all zeros. The matrix must be square with the number of dimensions defined by the number of entries in Axes.

The following example shows that males who are negative for STI coinfection are 3 times more likely to form relationships with females who are negative and, likewise, individuals positive for STI coinfection are more likely to form relationships with others of the same status.

{
    "Society": {
        "TRANSITORY": {
            "Pair_Formation_Parameters": {
                "Assortivity": {
                    "Group": "STI_COINFECTION_STATUS",
                    "Start_Year": 1990,
                    "Axes": [
                        "FALSE",
                        "TRUE"
                    ],
                    "Weighting_Matrix_RowMale_ColumnFemale": [
                        [
                            0.75,
                            0.25
                        ],
                        [
                            0.4,
                            0.6
                        ]
                    ]
                }
            }
        }
    }
}
Concurrency_Parameters

The Concurrency_Configuration section at the top level of the Society section defines the simultaneous relationship parameters for super spreader probabilities, whether simultaneous relationships type probabilities are independent or correlated, and, if correlated, the order of the relationship types. If you want to base concurrency on IndividualProperties settings, you can list the relevant properties in Individual_Property_Name, using “NONE” if the properties are irrelevant for concurrency.

Under each relationship type, the Concurrency_Parameters section defines simultaneous relationship parameters for that relationship type. In this section, all parameters should be nested under the name of the individual property relevant for setting concurrency. Again, if the properties are irrelevant, use “NONE”.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Concurrency_Parameters

JSON object

NA

NA

NA

The structure that determines how concurrent relationships are formed, for a specific relationship type. This parameter is nested under a parameter for one of the supported relationship types. To apply to all individuals regardless of individual property values, nest parameters under NONE. To apply only to individuals with certain property values, nest parameters under the property value as set in Concurrency_Configuration.

The following example sets concurrency for transitory relationships regardless of individual properties.

{
    "Society": {
        "TRANSITORY": {
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 2,
                    "Max_Simultaneous_Relationships_Male": 2,
                    "Prob_Extra_Relationship_Female": 0.3,
                    "Prob_Extra_Relationship_Male": 0.3
                }
            }
        }
    }
}

The following example sets different concurrency parameters for low-risk and high-risk individuals in transitory relationships.

{
    "Society": {
        "Concurrency_Configuration": {
            "Individual_Property_Name": "Risk",
            "LOW": {
                "Extra_Relational_Flag_Type": "Independent"
            },
            "HIGH": {
                "Extra_Relational_Flag_Type": "Correlated"
            }
        },
        "TRANSITORY": {
            "Concurrency_Parameters": {
                "LOW": {
                    "Max_Simultaneous_Relationships_Female": 2,
                    "Max_Simultaneous_Relationships_Male": 2,
                    "Prob_Extra_Relationship_Female": 0.3,
                    "Prob_Extra_Relationship_Male": 0.3
                },
                "HIGH": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 5,
                    "Prob_Extra_Relationship_Female": 0.5,
                    "Prob_Extra_Relationship_Male": 0.7
                }
            }
        }
    }
}

Max_Simultaneous_Relationships_Female

integer

0

63

1

For females, the maximum number of concurrent relationships. The individual sets the value at initialization and whenever they change relationship type.

 
{
    "Society": {
        "INFORMAL": {
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3,
                    "Prob_Extra_Relationship_Female": 0.8,
                    "Prob_Extra_Relationship_Male": 0.8
                }
            }
        }
    }
}

Max_Simultaneous_Relationships_Male

integer

0

63

1

For males, the maximum number of concurrent relationships.

 
{
    "Society": {
        "INFORMAL": {
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3,
                    "Prob_Extra_Relationship_Female": 0.8,
                    "Prob_Extra_Relationship_Male": 0.8
                }
            }
        }
    }
}

Prob_Extra_Relationship_Female

float

0

1

0

The probability of a female receiving a flag that allows her to seek additional relationships while currently in another relationship.

 
{
    "Society": {
        "INFORMAL": {
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3,
                    "Prob_Extra_Relationship_Female": 0.8,
                    "Prob_Extra_Relationship_Male": 0.8
                }
            }
        }
    }
}

Prob_Extra_Relationship_Male

float

0

1

0

The probability of a male receiving a flag that allows him to seek additional relationships while currently in another relationship.

 
{
    "Society": {
        "INFORMAL": {
            "Concurrency_Parameters": {
                "NONE": {
                    "Max_Simultaneous_Relationships_Female": 3,
                    "Max_Simultaneous_Relationships_Male": 3,
                    "Prob_Extra_Relationship_Female": 0.8,
                    "Prob_Extra_Relationship_Male": 0.8
                }
            }
        }
    }
}
Configuration parameters

The parameters described in this reference section can be added to the JSON (JavaScript Object Notation) formatted configuration file to determine the core behavior of a simulation including the computing environment, functionality to enable, additional files to use, and characteristics of the disease being modeled. This file contains mostly a flat list of JSON key:value pairs.

For more information on the structure of these files, see Configuration file.

The topics in this section contain only parameters available when using the HIV simulation type. Some parameters may appear in multiple categories.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Disease progression

The following parameters determine aspects of HIV progression from the acute stage to AIDS. For more information, see HIV symptoms and disease stages.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acute_Duration_In_Months

float

0

5

2.9

The time since infection, in months, over which the Acute_Stage_Infectivity_Multiplier is applied to coital acts occurring in that time period.

 
{
    "Acute_Duration_In_Months": 2.9
}

AIDS_Duration_In_Months

float

7

12

9

The length of time, in months, prior to an AIDS-related death over which the AIDS_Stage_Infectivity_Multiplier is applied.

 
{
    "AIDS_Duration_In_Months": 8
}
Drugs and treatments

The following parameters determine the efficacy of drugs and other treatments.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality

float

0

3.40E+38

350

The duration from ART enrollment to on-ART HIV-caused death increases with CD4 at ART initiation up to a threshold determined by this parameter value.

 
{
    "ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality": 350
}

Maternal_Transmission_ART_Multiplier

float

0

1

0.1

The maternal transmission multiplier for on-ART mothers.

 
{
    "Maternal_Transmission_ART_Multiplier": 0.03
}

Report_HIV_ByAgeAndGender_Collect_Intervention_Data

array of strings

NA

NA

NA

Stratifies the population by adding a column of 0s and 1s depending on whether or not the person has the indicated intervention. This only works for interventions that remain with a person for a period of time, such as ART, VMMC, vaccine/PrEP, or a delay state in the cascade of care. You can name the intervention by adding a parameter Intervention_Name in the campaign file, and then give this parameter the same Intervention_Name. This allows you to have multiple types of vaccines, VMMCs, etc., but to only stratify on the type you want.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Intervention_Data": [
        "ART_Intervention",
        "PrEP_Intervention"
    ]
}

Report_HIV_ByAgeAndGender_Collect_On_Art_Data

boolean

0

1

0

Controls whether or not the output report is stratified by those people who are on ART and those who are not. Set to true (1) to enable stratification by ART status.

 
{
    "Report_HIV_ByAgeAndGender_Collect_On_Art_Data": 1
}
Enable or disable features

The following parameters enable or disable features of the model, such as allowing births, deaths, or aging. Set to false (0) to disable; set to true (1) to enable.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Enable_Aging

boolean

0

1

1

Controls whether or not individuals in a population age during the simulation. Enable_Vital_Dynamics must be set to true (1).

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Aging": 1
}

Enable_Air_Migration

boolean

0

1

0

Controls whether or not migration by air travel will occur. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Air_Migration_Filename": "../inputs/air_migration.bin"
}

Enable_Birth

boolean

0

1

1

Controls whether or not individuals will be added to the simulation by birth. Enable_Vital_Dynamics must be set to true (1). If you want new individuals to have the same intervention coverage as existing individuals, you must add a BirthTriggeredIV to the campaign file.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1
}

Enable_Coital_Dilution

boolean

0

1

1

Controls whether or not coital dilution will occur.

 
{
    "Enable_Coital_Dilution": 1
}

Enable_Default_Reporting

boolean

0

1

1

Controls whether or not the default InsetChart.json report is created.

 
{
    "Enable_Default_Reporting": 1
}

Enable_Demographics_Birth

boolean

0

1

0

Controls whether or not newborns have disease risk drawn from a distribution; uniform disease risk if false. Enable_Birth, Enable_Demographics_Risk, and Enable_Vital_Dynamics must be set to true (1).

 
{
    "Enable_Birth": 1,
    "Enable_Demographics_Birth": 1,
    "Enable_Vital_Dynamics": 1
}

Enable_Demographics_Builtin

boolean

0

1

0

Controls whether or not built-in demographics for default geography will be used. Note that the built-in demographics feature does not represent a real geographical location and is mostly used for testing. Set to true (1) to define the initial population and number of nodes using Default_Geography_Initial_Node_Population and Default_Geography_Torus_Size. Set to false (0) to use demographics input files defined in Demographics_Filenames.

 
{
    "Enable_Demographics_Builtin": 1,
    "Default_Geography_Initial_Node_Population": 1000,
    "Default_Geography_Torus_Size": 3
}

Enable_Demographics_Reporting

boolean

0

1

1

Controls whether or not demographic summary data and age-binned reports are outputted to file.

 
{
    "Enable_Demographics_Reporting": 1
}

Enable_Family_Migration

boolean

0

1

0

Controls whether or not all members of a household can migrate together when a MigrateFamily event occurs. All residents must be home before they can leave on the trip. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Enable_Migration": "FIXED_RATE_MIGRATION",
    "Enable_Family_Migration": 1,
    "Family_Migration_Filename": "../inputs/family_migration.bin"
}

Enable_Heterogeneous_Intranode_Transmission

boolean

0

1

0

Controls whether or not individuals experience heterogeneous disease transmission within a node. When set to true (1), individual property definitions and the \(\beta\) matrix must be specified in the demographics file (see NodeProperties and IndividualProperties parameters). The \(\beta\) values are multiplied with the \(\beta\) 0 value configured by Base_Infectivity.

This is used only in generic, environmental, and typhoid simulations, but must be set to false (0) for all other simulation types. Heterogeneous transmission for other diseases uses other mechanistic parameters included with the simulation type.

 
{
    "Enable_Heterogeneous_Intranode_Transmission": 1
}

Enable_Infectivity_Reservoir

boolean

0

1

0

Controls whether or not an exogeneous reservoir of infectivity will be included in the simulation and allows for the infectivity in a node to be increased additively. When set to 1 (true), the demographics parameter InfectivityReservoirSize is expected in NodeAtttributes for each node.

Warning

Do not set both Enable_Infectivity_Reservoir and Enable_Strain_Tracking to true (1) - as this combination will cause an exception error.

 
{
    "Enable_Infectivity_Reservoir": 1
}

Enable_Initial_Susceptibility_Distribution

boolean

0

1

0

Controls whether or not individuals in the population have immunity at the beginning of the simulation. If set to 0, individuals are not initialized with immunity but may acquire immunity. If set to 1, you must indicate the type of distribution to use for immunity in the configuration parameter Immunity_Initialization_Distribution_Type and the distribution values in the demographics file. Enable_Immunity must be set to 1.

 
{
    "Enable_Immunity": 1,
    "Enable_Initial_Susceptibility_Distribution": 1,
    "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE"
}

Enable_Interventions

boolean

0

1

0

Controls whether or not campaign interventions will be used in the simulation. Set Campaign_Filename to the path of the file that contains the campaign interventions.

 
{
    "Enable_Interventions": 1,
    "Campaign_Filename": "campaign.json"
}

Enable_Local_Migration

boolean

0

1

0

Controls whether or not local migration (the diffusion of people in and out of nearby nodes by foot travel) occurs. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Local_Migration": 1,
    "Local_Migration_Filename": "../inputs/local_migration.bin"
}

Enable_Maternal_Infection_Transmission

boolean

0

1

0

Controls whether or not infectious mothers infect infants at birth. Enable_Birth must be set to 1 (true).

Warning

Do not set both Enable_Maternal_Infection_Transmission and Enable_Strain_Tracking to true (1) - as this combination will cause an exception error.

 
{
    "Enable_Birth": 1,
    "Enable_Maternal_Infection_Transmission": 1
}

Enable_Maternal_Protection

boolean

0

1

0

Controls whether or not mothers pass immunity on to their infants. Setting to 1 (true) enables maternal protection as defined by Maternal_Protection_Type. Enable_Birth must be set to 1 (true).

 
{
    "Enable_Maternal_Protection": 1,
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL"
}

Enable_Migration_Heterogeneity

boolean

0

1

1

Controls whether or not migration rate is heterogeneous among individuals within each group that has a migration rate setting. Set to true (1) to apply a migration rate distribution (see NodeAttributes demographics parameters); set to false (0) to use the same migration rate applied to all individuals in the group. For example, if you are using a migration file that sets different migration rates for each age group in a node, you could apply an Gaussian distribution around a mean value in each age group or you could assign the same value to each individual in each age group.

Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Migration_Heterogeneity": 1
}

Enable_Natural_Mortality

boolean

0

1

0

Controls whether or not individuals are removed from the simulation due to natural (non-disease) deaths. Enable_Vital_Dynamics must be set to 1 (true). Use Death_Rate_Dependence to set the natural death rate.

 
{
    "Enable_Natural_Mortality": 1,
    "Enable_Vital_Dynamics": 1
}

Enable_Property_Output

boolean

0

1

0

Controls whether or not to create property output reports, which detail groups as defined in IndividualProperties in the demographics file (see NodeProperties and IndividualProperties parameters). When there is more than one property type, the report will display the channel information for all combinations of the property type groups.

 
{
    "Enable_Property_Output": 1
}

Enable_Regional_Migration

boolean

0

1

0

Controls whether or not there is migration by road or rail network into and out of nodes in the simulation. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Regional_Migration": 1,
    "Regional_Migration_Filename": "../inputs/regional_migration.bin"
}

Enable_Sea_Migration

boolean

0

1

0

Controls whether or not there is migration on ships into and out of coastal cities with seaports. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Sea_Migration": 1,
    "Sea_Migration_Filename": "../inputs/sea_migration.bin"
}

Enable_Spatial_Output

boolean

0

1

0

Controls whether or not spatial output reports are created. If set to true (1), spatial output reports include all channels listed in the parameter Spatial_Output_Channels.

Note

Spatial output files require significant processing time and disk space.

 
{
    "Enable_Spatial_Output": 1,
    "Spatial_Output_Channels": [
        "Prevalence",
        "New_Infections"
    ]
}

Enable_Strain_Tracking

boolean

0

1

0

Enable an association of an infection with a specified strain, defined by unique integers for a clade and a genome.

For infections distributed through interventions, you specify clade and genome values using the Clade and Genome parameters with the Outbreak and OutbreakIndividual intervention classes in the campaign file.

When using an initial prevalence distribution, you specify clade and genome values using the InitialPrevalenceStrains parameter as part of IndividualAttributes in the demographics file.

When Enable_Strain_Tracking is set to false (0) or absent, all infections are associated with a single strain that has clade and genome identity (0, 0).

When Enable_Strain_Tracking is set to true (1) then both Number_of_Clades and Log2_Number_of_Genomes_per_Clade parameters must be specified.

Warning

Do not set both Enable_Strain_Tracking and Enable_Infectivity_Reservoir to true (1) or Enable_Strain_Tracking and Enable_Maternal_Infection_Transmission to true (1) - as these combinations will cause an exception error.

 
{
    "Enable_Strain_Tracking": 1,
    "Log2_Number_of_Genomes_per_Clade": 8,
    "Number_of_Clades": 2
}

Enable_Vital_Dynamics

boolean

0

1

1

Controls whether or not births and deaths occur in the simulation. Births and deaths must be individually enabled and set.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Death_Rate_Dependence": "NOT_INITIALIZED",
    "Base_Mortality": 0.002
}
General disease

The following parameters determine general disease characteristics.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Enable_Strain_Tracking

boolean

0

1

0

Enable an association of an infection with a specified strain, defined by unique integers for a clade and a genome.

For infections distributed through interventions, you specify clade and genome values using the Clade and Genome parameters with the Outbreak and OutbreakIndividual intervention classes in the campaign file.

When using an initial prevalence distribution, you specify clade and genome values using the InitialPrevalenceStrains parameter as part of IndividualAttributes in the demographics file.

When Enable_Strain_Tracking is set to false (0) or absent, all infections are associated with a single strain that has clade and genome identity (0, 0).

When Enable_Strain_Tracking is set to true (1) then both Number_of_Clades and Log2_Number_of_Genomes_per_Clade parameters must be specified.

Warning

Do not set both Enable_Strain_Tracking and Enable_Infectivity_Reservoir to true (1) or Enable_Strain_Tracking and Enable_Maternal_Infection_Transmission to true (1) - as these combinations will cause an exception error.

 
{
    "Enable_Strain_Tracking": 1,
    "Log2_Number_of_Genomes_per_Clade": 8,
    "Number_of_Clades": 2
}

Log2_Number_of_Genomes_per_Clade

integer

0

24

0

The maximum number of genome combinations per clades. Used with Number_of_Clades and dependent upon Enable_Strain_Tracking enabled, set to 1.

Note

Log2_Number_of_Genomes_per_Clade is internally fixed to 0 when using Typhoid and Malaria simulations.

 
{
    "Enable_Strain_Tracking": 1,
    "Log2_Number_of_Genomes_per_Clade": 8,
    "Number_of_Clades": 2
}

Number_of_Clades

integer

1

10

1

The maximum number of distinct clades in the simulation. Used with Log2_Number_of_Genomes_per_Clade to define the strain associated with an infection. Dependent upon Enable_Strain_Tracking enabled, set to 1.

 
{
    "Enable_Strain_Tracking": 1,
    "Log2_Number_of_Genomes_per_Clade": 8,
    "Number_of_Clades": 2
}
Geography and environment

The following parameters determine characteristics of the geography and environment of the simulation. For example, how to use the temperature or rainfall data in the climate files and the size of the nodes in the simulation.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Air_Temperature

float

-55

45

22

The air temperature, in degrees Celsius, where Climate_Model is set to CLIMATE_CONSTANT.

 
{
    "Climate_Model": "CLIMATE_CONSTANT",
    "Base_Air_Temperature": 30
}

Base_Land_Temperature

float

-55

60

26

The land temperature, in degrees Celsius, where Climate_Model is set to CLIMATE_CONSTANT.

 
{
    "Climate_Model": "CLIMATE_CONSTANT",
    "Base_Land_Temperature": 20
}

Base_Rainfall

float

0

150

10

The value of rainfall per day in millimeters when Climate_Model is set to CLIMATE_CONSTANT.

 
{
    "Climate_Model": "CLIMATE_CONSTANT",
    "Base_Rainfall": 20
}

Base_Relative_Humidity

float

0

1

0.75

The value of humidity where Climate_Model is set to CLIMATE_CONSTANT.

 
{
    "Base_Relative_Humidity": 0.1
}

Default_Geography_Initial_Node_Population

integer

0

1000000

1000

When using the built-in demographics for default geography, the initial number of individuals in each node. Note that the built-in demographics feature does not represent a real geographical location and is mostly used for testing. Enable_Demographics_Builtin must be set to true (1).

 
{
    "Enable_Demographics_Builtin": 1,
    "Default_Geography_Initial_Node_Population": 1000,
    "Default_Geography_Torus_Size": 3
}

Default_Geography_Torus_Size

integer

3

100

10

When using the built-in demographics for default geography, the square root of the number of nodes in the simulation. The simulation uses an N x N square grid of nodes with N specified by this parameter. If migration is enabled, the N x N nodes are assumed to be a torus and individuals can migrate from any node to all four adjacent nodes.

To enable migration, set Migration_Model to FIXED_RATE_MIGRATION. Built-in migration is a form of “local” migration where individuals only migrate to the adjacent nodes. You can use the x_Local_Migration parameter to control the rate of migration. The other migration parameters are ignored. Note that the built-in demographics feature does not represent a real geographical location and is mostly used for testing.

Enable_Demographics_Builtin must be set to true (1).

 
{
    "Enable_Demographics_Builtin": 1,
    "Default_Geography_Initial_Node_Population": 1000,
    "Default_Geography_Torus_Size": 3
}

Node_Grid_Size

float

0.00416

90

0.004167

The spatial resolution indicating the node grid size for a simulation in degrees.

 
{
    "Node_Grid_Size": 0.042
}
Immunity

The following parameters determine the immune system response for the disease being modeled, including waning immunity after an infection clears.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acquisition_Blocking_Immunity_Decay_Rate

float

0

1

0.001

The rate at which acquisition-blocking immunity decays after the initial period indicated by the base acquisition-blocking immunity offset. Only used when Enable_Immunity and Enable_Immune_Decay parameters are set to true (1).

 
{
    "Acquisition_Blocking_Immunity_Decay_Rate": 0.05
}

Acquisition_Blocking_Immunity_Duration_Before_Decay

float

0

45000

0

The number of days after infection until acquisition-blocking immunity begins to decay. Enable_Immunity and Enable_Immune_Decay must be set to true (1).

 
{
    "Acquisition_Blocking_Immunity_Duration_Before_Decay": 10
}

Enable_Initial_Susceptibility_Distribution

boolean

0

1

0

Controls whether or not individuals in the population have immunity at the beginning of the simulation. If set to 0, individuals are not initialized with immunity but may acquire immunity. If set to 1, you must indicate the type of distribution to use for immunity in the configuration parameter Immunity_Initialization_Distribution_Type and the distribution values in the demographics file. Enable_Immunity must be set to 1.

 
{
    "Enable_Immunity": 1,
    "Enable_Initial_Susceptibility_Distribution": 1,
    "Immunity_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE"
}

Enable_Maternal_Protection

boolean

0

1

0

Controls whether or not mothers pass immunity on to their infants. Setting to 1 (true) enables maternal protection as defined by Maternal_Protection_Type. Enable_Birth must be set to 1 (true).

 
{
    "Enable_Maternal_Protection": 1,
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL"
}

Immune_Threshold_For_Downsampling

float

0

1

0

The threshold on acquisition immunity at which to apply immunity-dependent downsampling; individuals who are more immune than this this threshold are downsampled. A value of 1 is equivalent to full susceptibility and 0 is equivalent to full immunity. If the acquisition immunity modifier is larger than the threshold, no downsampling occurs. Individual_Sampling_Type must set to ADAPTED_SAMPLING_BY_IMMUNE_STATE.

 
{
    "Relative_Sample_Rate_Immune": 0.1,
    "Immune_Threshold_For_Downsampling": 0.5,
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_IMMUNE_STATE"
}

Maternal_Linear_Slope

float

0.0001

1

0.01

Slope parameter describing the rate of waning for maternal protection, must be positive. The per-day increase in susceptibility. Maternal_Protection_Type must be set to LINEAR_FRACTIONAL or LINEAR_BINARY.

 
{
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL",
    "Maternal_Linear_SusZero": 0.45,
    "Maternal_Linear_Slope": 0.02
}

Maternal_Linear_SusZero

float

0

1

0.2

The initial level of maternal protection at age 0, given as susceptibility. A value of 0.0 implies total protection, a value of 1.0 implies no protection. Maternal_Protection_Type must be set to LINEAR_FRACTIONAL or LINEAR_BINARY.

 
{
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL",
    "Maternal_Linear_SusZero": 0.45,
    "Maternal_Linear_Slope": 0.02
}

Maternal_Protection_Type

enum

NA

NA

NONE

The type of maternal protection afforded to infants. Enable_Maternal_Protection must be set to 1 (true). Possible values are:

NONE

No immune protection is passed on to infants.

LINEAR

Susceptibility is a function of age and governed by a linear equation. Susceptibility = Maternal_Linear_Slope * age + Maternal_Linear_SusZero

SIGMOID

Susceptibility is a function of age and governed by a sigmoidal equation. Susceptibility = Maternal_Sigmoid_SusInit + (1.0 - Maternal_Sigmoid_SusInit) / * (1.0 + EXP(( Maternal_Sigmoid_HalfMaxAge - age) / Maternal_Sigmoid_SteepFac))

You must set Susceptibility_Type to determine if susceptibility at a particular age is interpreted as a fractional value or the probability of complete immunity or susceptibility.

 
{
    "Enable_Maternal_Protection": 1,
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL"
}

Maternal_Sigmoid_HalfMaxAge

float

-270

3650

180

The age in days that the level of maternal protection is half of its initial value. Maternal_Protection_Type must be set to SIGMOID_FRACTIONAL or SIGMOID_BINARY.

 
{
    "Maternal_Protection_Type": "SIGMOID_BINARY",
    "Maternal_Sigmoid_SteepFac": 30,
    "Maternal_Sigmoid_HalfMaxAge": 365,
    "Maternal_Sigmoid_SusInit": 0.0002
}

Maternal_Sigmoid_SteepFac

float

0.1

1000

30

The steepness factor describing the rate of waning for maternal protection, must be positive. Small values imply rapid waning.**Maternal_Protection_Type** must be set to SIGMOID_FRACTIONAL or SIGMOID_BINARY.

 
{
    "Maternal_Protection_Type": "SIGMOID_BINARY",
    "Maternal_Sigmoid_SteepFac": 30,
    "Maternal_Sigmoid_HalfMaxAge": 365,
    "Maternal_Sigmoid_SusInit": 0.0002
}

Maternal_Sigmoid_SusInit

float

0

1

0

The initial level of maternal protection at age -INF, given as susceptibility. A value of 0.0 implies total protection, a value of 1.0 implies no protection. Maternal_Protection_Type must be set to SIGMOID_FRACTIONAL or SIGMOID_BINARY.

 
{
    "Maternal_Protection_Type": "SIGMOID_BINARY",
    "Maternal_Sigmoid_SteepFac": 30,
    "Maternal_Sigmoid_HalfMaxAge": 365,
    "Maternal_Sigmoid_SusInit": 0.0002
}

Mortality_Blocking_Immunity_Decay_Rate

float

0

1

0.001

The rate at which mortality-blocking immunity decays after the mortality-blocking immunity offset period. Enable_Immune_Decay must be set to 1.

 
{
    "Mortality_Blocking_Immunity_Decay_Rate": 0.1
}

Mortality_Blocking_Immunity_Duration_Before_Decay

float

0

45000

0

The number of days after infection until mortality-blocking immunity begins to decay. Enable_Immunity and Enable_Immune_Decay must be set to 1.

 
{
    "Mortality_Blocking_Immunity_Duration_Before_Decay": 270
}

Post_Infection_Acquisition_Multiplier

float

0

1

0

The multiplicative reduction in the probability of reacquiring disease. At the time of recovery, the immunity against acquisition is multiplied by Acquisition_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Acquisition_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immune_Decay": 1,
    "Post_Infection_Acquisition_Multiplier": 0.9
}

Post_Infection_Mortality_Multiplier

float

0

1

0

The multiplicative reduction in the probability of dying from infection after getting reinfected. At the time of recovery, the immunity against mortality is multiplied by Mortality_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Mortality_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immune_Decay": 1,
    "Post_Infection_Mortality_Multiplier": 0.5
}

Post_Infection_Transmission_Multiplier

float

0

1

0

The multiplicative reduction in the probability of transmitting infection after getting reinfected. At the time of recovery, the immunity against transmission is multiplied by Transmission_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Transmission_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immunity_Decay": 1,
    "Post_Infection_Transmission_Multiplier": 0.9
}

Susceptibility_Initialization_Distribution_Type

enum

NA

NA

DISTRIBUTION_OFF

The method for initializing the susceptibility distribution in the simulated population. Enable_Initial_Susceptibility_Distribution must be set to 1 (true). Possible values are:

DISTRIBUTION_OFF

All individuals default to no susceptibility.

DISTRIBUTION_SIMPLE

Individual susceptibilities are drawn from a distribution whose functional form and parameters are specified in the demographics file in IndividualAttributes using SusceptibilityDistributionFlag, SusceptibilityDistribution1, and SusceptibilityDistribution2 (see Simple distributions parameters).

DISTRIBUTION_COMPLEX

Individual susceptibilities are drawn from an age-dependent piecewise linear function for each specific antibody in the demographics file (see Complex distributions parameters).

 
{
    "Enable_Immunity": 1,
    "Enable_Initial_Susceptibility_Distribution": 1,
    "Susceptibility_Initialization_Distribution_Type": "DISTRIBUTION_COMPLEX"
}

Susceptibility_Type

enum

NA

NA

FRACTIONAL

Controls implementation of an individual’s susceptibility. Currently only relevant to Maternal_Protection_Type parameter. Possible values are:

FRACTIONAL

All agents are assigned equal values between 0 and 1 according to a governing equation as specified by Maternal_Protection_Type.

BINARY

Agents receive a value of either 0 or 1 (complete immunity or susceptibility) with the probability determined by a governing equation as specified by Maternal_Protection_Type.

 
{
    "Susceptibility_Type": "FRACTIONAL",
    "Enable_Maternal_Protection": 1,
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL"
}

Transmission_Blocking_Immunity_Decay_Rate

float

0

1000

0.001

The rate at which transmission-blocking immunity decays after the base transmission-blocking immunity offset period. Used only when Enable_Immunity and Enable_Immune_Decay parameters are set to true (1).

 
{
    "Transmission_Blocking_Immunity_Decay_Rate": 0.01
}

Transmission_Blocking_Immunity_Duration_Before_Decay

float

0

45000

0

The number of days after infection until transmission-blocking immunity begins to decay. Only used when Enable_Immunity and Enable_Immune_Decay parameters are set to true (1).

 
{
    "Transmission_Blocking_Immunity_Duration_Before_Decay": 90
}
Incubation

The following parameters determine the characteristics of the incubation period.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Incubation_Period_Constant

float

0

3.40282E+38

-1

The incubation period, in days, to use for all individuals when Incubation_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Incubation_Period_Constant": 8
}

Incubation_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the incubation period to each individual in the population. Each individual’s value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Incubation_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Incubation_Period_Max and Incubation_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Incubation_Period_Gaussian_Mean and Incubation_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Incubation_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Incubation_Period_Kappa and Incubation_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Incubation_Period_Log_Normal_Mu and Incubation_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Incubation_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Incubation_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Incubation_Period_Mean_1, Incubation_Period_Mean_2, and Incubation_Period_Proportion_1. This distribution does not use the parameters set for DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Exponential

float

0

3.40282E+38

-1

The mean incubation period, in days, when Incubation_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Exponential": 4.25
}

Incubation_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the incubation period, in days, when Incubation_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the incubation period, in days, when Incubation_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Incubation_Period_Gaussian_Mean": 8,
    "Incubation_Period_Gaussian_Std_Dev": 1.5
}

Incubation_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the incubation period, in days, when Incubation_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Incubation_Period_Kappa": 0.9,
    "Incubation_Period_Lambda": 1.5
}

Incubation_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the incubation period, in days, when Incubation_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Incubation_Period_Kappa": 0.9,
    "Incubation_Period_Lambda": 1.5
}

Incubation_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the incubation period, in days, when Incubation_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Incubation_Period_Log_Normal_Mu": 4,
    "Incubation_Period_Log_Normal_Sigma": 1
}

Incubation_Period_Log_Normal_Sigma

float

1.17549E-38

3.40282E+38

1

The standard deviation of the natural log of the incubation period, in days, when Incubation_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Incubation_Period_Log_Normal_Mu": 4,
    "Incubation_Period_Log_Normal_Sigma": 1
}

Incubation_Period_Max

float

0

3.40282E+38

-1

The maximum incubation period, in days, when Incubation_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Incubation_Period_Min": 2,
    "Incubation_Period_Max": 7
}

Incubation_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Incubation_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Incubation_Period_Min

float

0

3.40282E+38

-1

The minimum incubation period, in days, when Incubation_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Incubation_Period_Min": 2,
    "Incubation_Period_Max": 7
}

Incubation_Period_Peak_2_Value

float

0

3.40282E+38

-1

The incubation period value, in days, to assign to the remaining individuals when Incubation_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Incubation_Period_Proportion_0": 0.25,
    "Incubation_Period_Peak_2_Value": 5
}

Incubation_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the incubation period, in days, when Incubation_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "POISSON_DISTRIBUTION",
    "Incubation_Period_Poisson_Mean": 5
}

Incubation_Period_Proportion_0

float

0

1

-1

The proportion of individuals to assign a value of zero days incubation when Incubation_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Incubation_Period_Proportion_0": 0.25,
    "Incubation_Period_Peak_2_Value": 5
}

Incubation_Period_Proportion_1

float

0

1

-1

The proportion of individuals in the first exponential distribution when Incubation_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Incubation_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Incubation_Period_Mean_1": 4,
    "Incubation_Period_Mean_2": 12,
    "Incubation_Period_Proportion_1": 0.2
}

Symptomatic_Infectious_Offset

float

-3.40282e+38

3.40282e+38

3.40282e+38

Amount of time, in days, after the infectious period starts that symptoms appear. Negative values imply an individual is symptomatic before infectious. If this offset is greater than the infectious duration, the infection will not be symptomatic. For example, if Incubation_Period_Constant is set to 10 and Symptomatic_Infectious_Offset is set to 4, then an infected person would become symptomatic 14 days after transmission.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Symptomatic_Infectious_Offset": 4,
    "Incubation_Period_Constant": 10
}
Infectivity and transmission

The following parameters determine aspects of infectivity and disease transmission. For example, how infectious individuals are and the length of time for which they remain infectious, whether the disease can be maternally transmitted, and how population density affects infectivity.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acute_Duration_In_Months

float

0

5

2.9

The time since infection, in months, over which the Acute_Stage_Infectivity_Multiplier is applied to coital acts occurring in that time period.

 
{
    "Acute_Duration_In_Months": 2.9
}

Acute_Stage_Infectivity_Multiplier

float

1

100

26

The multiplier acting on Base_Infectivity to determine the per-act transmission probability of an HIV+ individual during the acute stage.

 
{
    "Acute_Stage_Infectivity_Multiplier": 3
}

AIDS_Stage_Infectivity_Multiplier

float

1

100

10

The multiplier acting on Base_Infectivity to determine the per-act transmission probability of an HIV+ individual during the AIDS stage.

 
{
    "AIDS_Stage_Infectivity_Multiplier": 8
}

ART_Viral_Suppression_Multiplier

float

0

1

0.08

Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV+ individual.

 
{
    "ART_Viral_Suppression_Multiplier": 0.3
}

Base_Infectivity

float

0

1000

0.3

The base infectiousness of individuals before accounting for transmission-blocking effects of acquired immunity and/or campaign interventions.

For STI or HIV simulations, this is the probability of transmission when none of the transmission multipliers apply to a particular coital act (or when all multipliers are set to 1).

 
{
    "Base_Infectivity": 0.5
}

CD4_At_Death_LogLogistic_Heterogeneity

float

0

100

0

The inverse shape parameter of a Weibull distribution that represents the at-death CD4 cell count.

 
{
    "CD4_At_Death_LogLogistic_Heterogeneity": 0.7
}

Condom_Transmission_Blocking_Probability

float

0

1

0.9

The per-act multiplier of the transmission probability when a condom is used.

 
{
    "Condom_Transmission_Blocking_Probability": 0.99
}

Enable_Heterogeneous_Intranode_Transmission

boolean

0

1

0

Controls whether or not individuals experience heterogeneous disease transmission within a node. When set to true (1), individual property definitions and the \(\beta\) matrix must be specified in the demographics file (see NodeProperties and IndividualProperties parameters). The \(\beta\) values are multiplied with the \(\beta\) 0 value configured by Base_Infectivity.

This is used only in generic, environmental, and typhoid simulations, but must be set to false (0) for all other simulation types. Heterogeneous transmission for other diseases uses other mechanistic parameters included with the simulation type.

 
{
    "Enable_Heterogeneous_Intranode_Transmission": 1
}

Enable_Infectivity_Reservoir

boolean

0

1

0

Controls whether or not an exogeneous reservoir of infectivity will be included in the simulation and allows for the infectivity in a node to be increased additively. When set to 1 (true), the demographics parameter InfectivityReservoirSize is expected in NodeAtttributes for each node.

Warning

Do not set both Enable_Infectivity_Reservoir and Enable_Strain_Tracking to true (1) - as this combination will cause an exception error.

 
{
    "Enable_Infectivity_Reservoir": 1
}

Enable_Maternal_Infection_Transmission

boolean

0

1

0

Controls whether or not infectious mothers infect infants at birth. Enable_Birth must be set to 1 (true).

Warning

Do not set both Enable_Maternal_Infection_Transmission and Enable_Strain_Tracking to true (1) - as this combination will cause an exception error.

 
{
    "Enable_Birth": 1,
    "Enable_Maternal_Infection_Transmission": 1
}

Enable_Skipping

boolean

0

1

0

Controls whether or not the simulation uses an optimization that can increase performance by up to 50% in some cases by probabilistically exposing individuals rather than exposing every single person. Useful in low-prevalence, high-population scenarios.

 
{
    "Enable_Skipping": 0
}

Enable_Termination_On_Zero_Total_Infectivity

boolean

0

1

0

Controls whether or not the simulation should be ended when total infectivity falls to zero. Supported only in single-node simulations.

 
{
    "Enable_Termination_On_Zero_Total_Infectivity": 1,
    "Minimum_End_Time": 3650
}

Heterogeneous_Infectiousness_LogNormal_Scale

float

0

10

0

Scale parameter of a log normal distribution that governs an infectiousness multiplier. The multiplier represents heterogeneity in infectivity and adjusts Base_Infectivity.

 
{
    "Heterogeneous_Infectiousness_LogNormal_Scale": 1
}

Infection_Updates_Per_Timestep

integer

0

144

1

The number of infection updates executed during each timestep; note that a timestep defaults to one day.

 
{
    "Infection_Updates_Per_Timestep": 1
}

Infectious_Period_Constant

float

0

3.40282E+38

-1

The infectious period to use for all individuals, in days, when Infectious_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Infectious_Period_Constant": 8
}

Infectious_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the infectious period to each individual in the population. Each individual’s value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Infectious_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Infectious_Period_Max and Infectious_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Infectious_Period_Gaussian_Mean and Infectious_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Infectious_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Infectious_Period_Kappa and Infectious_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Infectious_Period_Log_Normal_Mu and Infectious_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Infectious_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Infectious_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Infectious_Period_Mean_1, Infectious_Period_Mean_2, and Infectious_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Exponential

float

0

3.40282E+38

-1

The mean infectious period, in days, when Infectious_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Exponential": 4.25
}

Infectious_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean infectious period, in days, when Infectious_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the infectious period, in days, when Infectious_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Infectious_Period_Gaussian_Mean": 4,
    "Infectious_Period_Gaussian_Std_Dev": 1
}

Infectious_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the infectious period, in days, when Infectious_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Infectious_Period_Kappa": 0.9,
    "Infectious_Period_Lambda": 1.5
}

Infectious_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the infectious period, in days, when Infectious_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Infectious_Period_Kappa": 0.9,
    "Infectious_Period_Lambda": 1.5
}

Infectious_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the infectious period, in days, when Infectious_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Infectious_Period_Log_Normal_Mu": 9,
    "Infectious_Period_Log_Normal_Sigma": 2
}

Infectious_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282e+38

The standard deviation of the natural log of the infectious period, in days, when Infectious_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Infectious_Period_Log_Normal_Mu": 9,
    "Infectious_Period_Log_Normal_Sigma": 2
}

Infectious_Period_Max

float

0

3.40282E+38

-1

The maximum infectious period, in days, when Infectious_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Infectious_Period_Min": 2,
    "Infectious_Period_Max": 7
}

Infectious_Period_Mean_1

float

1.17549E-38

3.4E+38

-1

The mean of the first exponential distribution, in days, when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Infectious_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Infectious_Period_Min

float

0

3.40282E+38

-1

The minimum infectious period, in days, when Infectious_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Infectious_Period_Min": 2,
    "Infectious_Period_Max": 7
}

Infectious_Period_Peak_2_Value

float

0

3.40282E+38

-1

The infectious period value, in days, to assign to the remaining individuals when Infectious_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Infectious_Period_Proportion_0": 0.25,
    "Infectious_Period_Peak_2_Value": 5
}

Infectious_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the infectious period, in days, when Infectious_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "POISSON_DISTRIBUTION",
    "Infectious_Period_Poisson_Mean": 5
}

Infectious_Period_Proportion_0

float

0

1

-1

The proportion of individuals to assign a value of zero days infectiousness when Infectious_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Infectious_Period_Proportion_0": 0.25,
    "Infectious_Period_Peak_2_Value": 5
}

Infectious_Period_Proportion_1

float

0

1

-1

The proportion of individuals in the first exponential distribution when Infectious_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Infectious_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Infectious_Period_Mean_1": 4,
    "Infectious_Period_Mean_2": 12,
    "Infectious_Period_Proportion_1": 0.2
}

Infectivity_Exponential_Baseline

float

0

1

0

The scale factor applied to Base_Infectivity at the beginning of a simulation, before the infectivity begins to grow exponentially. Infectivity_Scale_Type must be set to EXPONENTIAL_FUNCTION_OF_TIME.

 
{
    "Infectivity_Exponential_Baseline": 0.1,
    "Infectivity_Exponential_Delay": 90,
    "Infectivity_Exponential_Rate": 45,
    "Infectivity_Scale_Type": "EXPONENTIAL_FUNCTION_OF_TIME"
}

Male_To_Female_Relative_Infectivity_Ages

array of floats

NA

NA

0

The vector of ages governing the susceptibility of females relative to males, by age. Used with Male_To_Female_Relative_Infectivity_Multipliers.

 
{
    "Male_To_Female_Relative_Infectivity_Ages": [
        15,
        25,
        35
    ]
}

Male_To_Female_Relative_Infectivity_Multipliers

array of floats

NA

NA

1

An array of scale factors governing the susceptibility of females relative to males, by age. Used with Male_To_Female_Relative_Infectivity_Ages. Scaling is linearly interpolated between ages. The first value is used for individuals younger than the first age in Male_To_Female_Relative_Infectivity_Ages and the last value is used for individuals older than the last age.

 
{
    "Male_To_Female_Relative_Infectivity_Multipliers": [
        5,
        1,
        0.5
    ]
}

Maternal_Infection_Transmission_Probability

float

0

1

0

The probability of transmission of infection from mother to infant at birth. Enable_Maternal_Infection_Transmission must be set to 1.

Note

For malaria and vector simulations, set this to 0. Instead, use the Maternal_Antibody_Protection, Maternal_Antibody_Decay_Rate, and Maternal_Antibodies_Type parameters.

 
{
    "Maternal_Infection_Transmission_Probability": 0.3
}

Maternal_Transmission_ART_Multiplier

float

0

1

0.1

The maternal transmission multiplier for on-ART mothers.

 
{
    "Maternal_Transmission_ART_Multiplier": 0.03
}

Population_Density_C50

float

0

3.40E+38

10

The population density at which R0 for a 2.5-arc minute square reaches half of its initial value. Population_Density_Infectivity_Correction must be set to SATURATING_FUNCTION_OF_DENSITY.

 
{
    "Population_Density_C50": 30
}

Population_Density_Infectivity_Correction

enum

NA

NA

CONSTANT_INFECTIVITY

Correction to alter infectivity by population density set in the Population_Density_C50 parameter. Measured in people per square kilometer. Possible values are:

  • CONSTANT_INFECTIVITY

  • SATURATING_FUNCTION_OF_DENSITY

Note

Sparsely populated areas have a lower infectivity, while densely populated areas have a higher infectivity, which rises to saturate at the Base_Infectivity value.

 
{
    "Population_Density_Infectivity_Correction": "SATURATING_FUNCTION_OF_DENSITY"
}

Relative_Sample_Rate_Immune

float

0.001

1

0.1

The relative sampling rate for people who have acquired immunity through recovery or vaccination. The immune threshold at which to downsample is set by Immune_Threshold_For_Downsampling. If set to 1, this will have no effect, even if the individual’s immunity modifier is below threshold. This can be a useful sanity check while learning this feature. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_IMMUNE_STATE.

 
{
    "Relative_Sample_Rate_Immune": 0.1,
    "Immune_Threshold_For_Downsampling": 0.8,
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_IMMUNE_STATE"
}

STI_Coinfection_Acquisition_Multiplier

float

0

100

10

The per-act HIV acquisition probability multiplier for individuals with the STI coinfection flag.

 
{
    "STI_Coinfection_Transmission_Multiplier": 13.4,
    "STI_Coinfection_Acquisition_Multiplier": 10
}

STI_Coinfection_Transmission_Multiplier

float

0

100

10

The per-act HIV transmission probability multiplier for individuals with the STI coinfection flag.

 
{
    "STI_Coinfection_Transmission_Multiplier": 13.4,
    "STI_Coinfection_Acquisition_Multiplier": 10
}

Susceptibility_Type

enum

NA

NA

FRACTIONAL

Controls implementation of an individual’s susceptibility. Currently only relevant to Maternal_Protection_Type parameter. Possible values are:

FRACTIONAL

All agents are assigned equal values between 0 and 1 according to a governing equation as specified by Maternal_Protection_Type.

BINARY

Agents receive a value of either 0 or 1 (complete immunity or susceptibility) with the probability determined by a governing equation as specified by Maternal_Protection_Type.

 
{
    "Susceptibility_Type": "FRACTIONAL",
    "Enable_Maternal_Protection": 1,
    "Maternal_Protection_Type": "LINEAR_FRACTIONAL"
}

Symptomatic_Infectious_Offset

float

-3.40282e+38

3.40282e+38

3.40282e+38

Amount of time, in days, after the infectious period starts that symptoms appear. Negative values imply an individual is symptomatic before infectious. If this offset is greater than the infectious duration, the infection will not be symptomatic. For example, if Incubation_Period_Constant is set to 10 and Symptomatic_Infectious_Offset is set to 4, then an infected person would become symptomatic 14 days after transmission.

 
{
    "Infectious_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Symptomatic_Infectious_Offset": 4,
    "Incubation_Period_Constant": 10
}

Transmission_Blocking_Immunity_Decay_Rate

float

0

1000

0.001

The rate at which transmission-blocking immunity decays after the base transmission-blocking immunity offset period. Used only when Enable_Immunity and Enable_Immune_Decay parameters are set to true (1).

 
{
    "Transmission_Blocking_Immunity_Decay_Rate": 0.01
}

Transmission_Blocking_Immunity_Duration_Before_Decay

float

0

45000

0

The number of days after infection until transmission-blocking immunity begins to decay. Only used when Enable_Immunity and Enable_Immune_Decay parameters are set to true (1).

 
{
    "Transmission_Blocking_Immunity_Duration_Before_Decay": 90
}
Input files

The following parameters set the paths to the the campaign file and the input files for climate, migration, demographics, and load-balancing.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Air_Migration_Filename

string

NA

NA

_add-your-air-migration-file_.json

The path to the input file that defines patterns of migration by airplane. Enable_Air_Migration must be set to true (1). See Migration files for information on migration files.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Air_Migration_Filename": "../Global_1degree_air_migration.bin"
}

Campaign_Filename

string

NA

NA

The path to the campaign file. It is required when interventions are part of the simulation and Enable_Interventions is set to true (1). The file must be in .json format.

 
{
    "Enable_Interventions": 1,
    "Campaign_Filename": "campaign.json"
}

Demographics_Filenames

array of strings

NA

NA

An array of the paths to demographics files containing information on the identity and demographics of the region to simulate. The files must be in .json format. Note that this parameter is only required when Enable_Demographics_Builtin is set to 0.

 
{
    "Demographics_Filenames": [
        "Namawala_single_node_demographics.json",
        "Namawala_demographics_overlay.json"
    ]
}

Family_Migration_Filename

string

NA

NA

_add-your-family-migration-file_.json

The name of the binary file to use to configure family migration. Enable_Family_Migration must be set to true (1). See Migration files for information on migration files.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Family_Migration": 1,
    "Family_Migration_Filename": "../inputs/family_migration.bin"
}

Load_Balance_Filename

string

NA

NA

UNINITIALIZED STRING

The path to the input file used when a static load balancing scheme is selected. The file must be in .json format.

 
{
    "Load_Balance_Filename": "GitHub_426_LoadBalance.json"
}

Local_Migration_Filename

string

NA

NA

_add-your-local-migration-file_.json

The path of the input file which defines patterns of migration to adjacent nodes by foot travel. See Migration files for information on migration files.

 
{
    "Local_Migration_Filename": "Local_Migration.bin"
}

Regional_Migration_Filename

string

NA

NA

_add-your-regional-migration-file_.json

The path of the input file which defines patterns of migration by vehicle via road or rail network. If the node is not on a road or rail network, regional migration focuses on the closest hub city in the network. The file must be in .bin format. See Migration files for information on migration files.

 
{
    "Regional_Migration_Filename": "Regional_Migration.bin"
}

Sea_Migration_Filename

string

NA

NA

_add-your-sea-migration-file_.json

The path of the input file which defines patterns of migration by ship. Only used when Enable_Sea_Migration is set to true (1). The file must be in .bin format. See Migration files for information on migration files.

 
{
    "Sea_Migration_Filename": "5x5_Households_Work_Migration.bin"
}

Serialized_Population_Filenames

array of strings

NA

NA

NA

An array of filenames with serialized population data. The number of filenames must match the number of cores used for the simulation. The files must be in .dtk format. Serialized population files are created using Serialization_Time_Steps.

 
{
    "Serialized_Population_Filenames": [
        "state-00010.dtk"
    ]
}

Serialized_Population_Path

string

NA

NA

.

The root path for the serialized population files. Serialized population files are created using Serialization_Time_Steps.

 
{
    "Serialized_Population_Path": "../00_Generic_Version_1_save/output"
}
Migration

The following parameters determine aspects of population migration into and outside of a node, including daily commutes, seasonal migration, and one-way moves. Modes of transport includes travel by foot, automobile, sea, or air. Migration can also be configured to move all individuals in a family at the same time.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Air_Migration_Filename

string

NA

NA

_add-your-air-migration-file_.json

The path to the input file that defines patterns of migration by airplane. Enable_Air_Migration must be set to true (1). See Migration files for information on migration files.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Air_Migration_Filename": "../Global_1degree_air_migration.bin"
}

Air_Migration_Roundtrip_Duration

float

0

10000

1

The average time spent (in days) at the destination node during a round-trip migration by airplane. Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Air_Migration_Roundtrip_Duration": 2
}

Air_Migration_Roundtrip_Probability

float

0

1

0.8

The likelihood that an individual who flies to another node will return to the node of origin during the next migration. Enable_Air_Migration must be set to true (1).

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Air_Migration_Roundtrip_Probability": 0.9
}

Enable_Air_Migration

boolean

0

1

0

Controls whether or not migration by air travel will occur. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Air_Migration": 1,
    "Air_Migration_Filename": "../inputs/air_migration.bin"
}

Enable_Family_Migration

boolean

0

1

0

Controls whether or not all members of a household can migrate together when a MigrateFamily event occurs. All residents must be home before they can leave on the trip. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Enable_Migration": "FIXED_RATE_MIGRATION",
    "Enable_Family_Migration": 1,
    "Family_Migration_Filename": "../inputs/family_migration.bin"
}

Enable_Local_Migration

boolean

0

1

0

Controls whether or not local migration (the diffusion of people in and out of nearby nodes by foot travel) occurs. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Local_Migration": 1,
    "Local_Migration_Filename": "../inputs/local_migration.bin"
}

Enable_Migration_Heterogeneity

boolean

0

1

1

Controls whether or not migration rate is heterogeneous among individuals within each group that has a migration rate setting. Set to true (1) to apply a migration rate distribution (see NodeAttributes demographics parameters); set to false (0) to use the same migration rate applied to all individuals in the group. For example, if you are using a migration file that sets different migration rates for each age group in a node, you could apply an Gaussian distribution around a mean value in each age group or you could assign the same value to each individual in each age group.

Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Migration_Heterogeneity": 1
}

Enable_Regional_Migration

boolean

0

1

0

Controls whether or not there is migration by road or rail network into and out of nodes in the simulation. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Regional_Migration": 1,
    "Regional_Migration_Filename": "../inputs/regional_migration.bin"
}

Enable_Sea_Migration

boolean

0

1

0

Controls whether or not there is migration on ships into and out of coastal cities with seaports. Migration_Model must be set to FIXED_RATE_MIGRATION.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Sea_Migration": 1,
    "Sea_Migration_Filename": "../inputs/sea_migration.bin"
}

Family_Migration_Filename

string

NA

NA

_add-your-family-migration-file_.json

The name of the binary file to use to configure family migration. Enable_Family_Migration must be set to true (1). See Migration files for information on migration files.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Enable_Family_Migration": 1,
    "Family_Migration_Filename": "../inputs/family_migration.bin"
}

Family_Migration_Roundtrip_Duration

float

0

10000

1

The number of days to complete the trip and return to the original node. Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Enable_Family_Migration": 1,
    "Family_Migration_Roundtrip_Duration": 100
}

Local_Migration_Filename

string

NA

NA

_add-your-local-migration-file_.json

The path of the input file which defines patterns of migration to adjacent nodes by foot travel. See Migration files for information on migration files.

 
{
    "Local_Migration_Filename": "Local_Migration.bin"
}

Local_Migration_Roundtrip_Duration

float

0

10000

1

The average time spent (in days) at the destination node during a round-trip migration by foot travel. Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Enable_Local_Migration": 1,
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Local_Migration_Roundtrip_Duration": 1.0
}

Local_Migration_Roundtrip_Probability

float

0

1

0.95

The likelihood that an individual who walks into a neighboring node will return to the node of origin during the next migration. Only used when Enable_Local_Migration is set to true (1).

 
{
    "Local_Migration_Roundtrip_Probability": 1.0
}

Migration_Model

enum

NA

NA

NO_MIGRATION

Model to use for migration. Possible values are:

NO_MIGRATION

Migration into and out of nodes will not occur.

FIXED_RATE_MIGRATION

Migration into and out of nodes will occur at a fixed rate as defined in the migration files. At the beginning of the simulation or whenever an individual has just moved, they pick their next destination and the time and type of the migration. If an individual is on an outbound leg of their journey, they will query the node’s MigrationInfo object and, through probability, pick a new destination; if the individual is inbound, they will travel back to their previous location.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Local_Migration_Filename": "../inputs/local_migration.bin",
    "Enable_Local_Migration": 1
}

Migration_Pattern

enum

NA

NA

RANDOM_WALK_DIFFUSION

Describes the pattern of travel used during migration. Migration_Model must be set to FIXED_RATE_MIGRATION. Possible values are:

RANDOM_WALK_DIFFUSION

Individuals retain no memory of where they came from; every move is to a new destination with no thought of returning home.

SINGLE_ROUND_TRIPS

Individuals have a probability (determined Local_Migration_Roundtrip_Probability, Air_Migration_Roundtrip_Probability, etc.) that they will return to their original location after some duration of time. If they do not, the current location is the new departure point for migration, but their original location remains their home node.

WAYPOINTS_HOME

Individuals go on a multi-step journey along several waypoints and then retrace their steps back along their path once they have reached a maximum number of waypoints from their home node. For example, the path of travel would be 1 -> 2 -> 3 -> 4 -> 3 -> 2 -> 1 if their home is node 1. On the outbound journey, the duration at each waypoint is not set explicitly but is determined by each node’s migration rate; on the return journey, one timestep is spent at each waypoint.

 
{
    "Migration_Model": "FIXED_RATE_MIGRATION",
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Enable_Local_Migration": 1,
    "Local_Migration_Roundtrip_Probability": 0.05,
    "Local_Migration_Roundtrip_Duration": 10
}

Regional_Migration_Filename

string

NA

NA

_add-your-regional-migration-file_.json

The path of the input file which defines patterns of migration by vehicle via road or rail network. If the node is not on a road or rail network, regional migration focuses on the closest hub city in the network. The file must be in .bin format. See Migration files for information on migration files.

 
{
    "Regional_Migration_Filename": "Regional_Migration.bin"
}

Regional_Migration_Roundtrip_Duration

float

0

10000

1

The average time spent (in days) at the destination node during a round-trip migration by road network. Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Enable_Regional_Migration": 1,
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Regional_Migration_Roundtrip_Duration": 1.0
}

Regional_Migration_Roundtrip_Probability

float

0

1

0.1

The likelihood that an individual who travels by vehicle to another node will return to the node of origin during the next migration. Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Regional_Migration_Roundtrip_Probability": 1.0
}

Roundtrip_Waypoints

integer

0

1000

10

The maximum number of points reached during a trip before steps are retraced on the return trip home. Migration_Pattern must be set to WAYPOINTS_HOME.

 
{
    "Roundtrip_Waypoints": 5
}

Sea_Migration_Filename

string

NA

NA

_add-your-sea-migration-file_.json

The path of the input file which defines patterns of migration by ship. Only used when Enable_Sea_Migration is set to true (1). The file must be in .bin format. See Migration files for information on migration files.

 
{
    "Sea_Migration_Filename": "5x5_Households_Work_Migration.bin"
}

Sea_Migration_Roundtrip_Duration

float

0

10000

1

The average time spent at the destination node during a round-trip migration by ship. Used only when Migration_Pattern must be set to SINGLE_ROUND_TRIPS.

 
{
    "Enable_Sea_Migration": 1,
    "Migration_Pattern": "SINGLE_ROUND_TRIPS",
    "Sea_Migration_Roundtrip_Duration": 10000
}

Sea_Migration_Roundtrip_Probability

float

0

1

0.25

The likelihood that an individual who travels by ship into a neighboring node will return to the node of origin during the next migration. Used only when Enable_Sea_Migration is set to true (1).

 
{
    "Sea_Migration_Roundtrip_Probability": 0
}

x_Air_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by air, as provided by the migration file. Enable_Air_Migration must be set to 1.

 
{
    "Scale_Factor_Air_Migration": 1
}

x_Family_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by families, as provided by the migration file. Enable_Family_Migration must be set to true (1).

 
{
    "x_Family_Migration": 1
}

x_Local_Migration

float

0

3.40E+38

1

Scale factor for rate of migration by foot travel, as provided by the migration file. Enable_Local_Migration must be set to 1.

 
{
    "x_Local_Migration": 1
}

x_Regional_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by road vehicle, as provided by the migration file. Enable_Regional_Migration must be set to 1.

 
{
    "x_Regional_Migration": 1
}

x_Sea_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by sea, as provided by the migration file. Enable_Sea_Migration must be set to 1.

 
{
    "x_Sea_Migration": 1
}
Mortality and survival

The following parameter determine mortality and survival characteristics of the disease being modeled and the population in general (non-disease mortality).

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality

float

0

3.40E+38

350

The duration from ART enrollment to on-ART HIV-caused death increases with CD4 at ART initiation up to a threshold determined by this parameter value.

 
{
    "ART_CD4_at_Initiation_Saturating_Reduction_in_Mortality": 350
}

Base_Mortality

float

0

1000

0.001

The base mortality of the infection before accounting for individual immune modification factors. Depending on the setting of Mortality_Time_Course, this is either the daily probability of the disease being fatal (DAILY_MORTALITY) or the probability of death at the end of the infection duration (MORTALITY_AFTER_INFECTIOUS). Enable_Disease_Mortality must be set to 1 (true).

 
{
    "Enable_Vital_Dynamics": 1,
    "Mortality_Time_Course": "DAILY_MORTALITY",
    "Base_Mortality": 0.01
}

Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity

float

0.1

10

1

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the heterogeneity (inverse shape) of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity": 0.5
}

Days_Between_Symptomatic_And_Death_Weibull_Scale

float

1

3650

183

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the scale of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Scale": 618.3
}

Death_Rate_Dependence

enum

NA

NA

NOT_INITIALIZED

Determines how likely individuals are to die from natural, non-disease causes. Enable_Natural_Mortality must be set to 1. Possible values are:

NOT_INITIALIZED

The daily mortality rate is 0, and no one dies from non-disease related causes.

NONDISEASE_MORTALITY_BY_AGE_AND_GENDER

The individual’s age and gender are taken into account to determine the daily mortality rate.

NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER

Gender, age, and year, are all taken into account to determine the daily mortality rate.

Properties, rates, and bin sizes can be set for non-disease mortality for each gender in the demographics file (see Complex distributions parameters).

 
{
    "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER"
}

Enable_Natural_Mortality

boolean

0

1

0

Controls whether or not individuals are removed from the simulation due to natural (non-disease) deaths. Enable_Vital_Dynamics must be set to 1 (true). Use Death_Rate_Dependence to set the natural death rate.

 
{
    "Enable_Natural_Mortality": 1,
    "Enable_Vital_Dynamics": 1
}

HIV_Adult_Survival_Scale_Parameter_Intercept

float

0.001

1000

21.182

This parameter determines the intercept of the scale parameter, ?, for the Weibull distribution used to determine HIV survival time.

Survival time with untreated HIV infection depends on the age of the individual at the time of infection, and is drawn from a Weibull distribution with shape parameter (see HIV_Adult_Survival_Shape_Parameter) and scale parameter, ?. The scale parameter is allowed to vary linearly with age as follows:

\(\lambda\) = HIV_Adult_Survival_Scale_Parameter_Intercept + HIV_Adult_Survival_Scale_ Parameter_Slope * Age (in years).

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Adult_Survival_Scale_Parameter_Slope

float

-1000

1000

-0.2717

This parameter determines the slope of the scale parameter, ?, for the Weibull distribution used to determine HIV survival time.

Survival time with untreated HIV infection depends on the age of the individual at the time of infection, and is drawn from a Weibull distribution with shape parameter (see HIV_Adult_Survival_Shape_Parameter) and scale parameter, ?. The scale parameter is allowed to vary linearly with age as follows:

\(\lambda\) = HIV_Adult_Survival_Scale_Parameter_Intercept + HIV_Adult_Survival_Scale_ Parameter_Slope * Age (in years).

Because survival time with HIV becomes shorter with increasing age, HIV_Adult_Survival_Scale_ Parameter_Slope should be set to a negative number.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Adult_Survival_Shape_Parameter

float

0.001

1000

2

This parameter determines the shape of the Weibull distribution used to determine age-dependent survival time for individuals infected with HIV.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Age_Max_for_Adult_Age_Dependent_Survival

float

0

75

70

Survival time with untreated HIV infection depends on the age of the individual at the time of infection, and is drawn from a Weibull distribution with shape parameter and scale parameter, ?. See HIV_Adult_Survival_Scale_Parameter_Intercept, HIV_Adult_Survival_Scale_ Parameter_Slope, and HIV_Adult_Survival_Shape_Parameter.

Although the scale parameter for survival time declines with age, it cannot become negative. To avoid negative survival times at older ages, this parameter, HIV_Age_Max_for_Adult_Age_Dependent_Survival, determines the age beyond which HIV survival is no longer affected by further aging.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Age_Max_for_Child_Survival_Function

float

0

75

15

The maximum age at which an individual’s survival will be fit to the child survival function. If the value of this parameter falls between zero and the age of sexual debut, model results are not sensitive to this parameter as there is no mechanism for children to become infected between infancy and sexual debut.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0,
    "HIV_Age_Max_for_Child_Survival_Function": 15.0
}

HIV_Child_Survival_Rapid_Progressor_Fraction

float

0

1

0.57

The proportion of HIV-infected children who are rapid HIV progressors.

 
{
    "HIV_Child_Survival_Rapid_Progressor_Fraction": 0.57,
    "HIV_Child_Survival_Rapid_Progressor_Rate": 1.52
}

HIV_Child_Survival_Rapid_Progressor_Rate

float

0

1000

1.52

The exponential decay rate, in years, describing the distribution of HIV survival for children who are rapid progressors.

 
{
    "HIV_Child_Survival_Rapid_Progressor_Fraction": 0.57,
    "HIV_Child_Survival_Rapid_Progressor_Rate": 1.52
}

HIV_Child_Survival_Slow_Progressor_Scale

float

0.001

1000

16

The Weibull scale parameter describing the distribution of HIV survival for children who are slower progressors.

 
{
    "HIV_Child_Survival_Slow_Progressor_Scale": 16.0,
    "HIV_Child_Survival_Slow_Progressor_Shape": 2.7
}

HIV_Child_Survival_Slow_Progressor_Shape

float

0.001

1000

2.7

The Weibull shape parameter describing the distribution of HIV survival for children who are slower progressors.

 
{
    "HIV_Child_Survival_Slow_Progressor_Scale": 16.0,
    "HIV_Child_Survival_Slow_Progressor_Shape": 2.7
}

Mortality_Blocking_Immunity_Decay_Rate

float

0

1

0.001

The rate at which mortality-blocking immunity decays after the mortality-blocking immunity offset period. Enable_Immune_Decay must be set to 1.

 
{
    "Mortality_Blocking_Immunity_Decay_Rate": 0.1
}

Mortality_Time_Course

enum

NA

NA

DAILY_MORTALITY

The method used to calculate disease deaths. Enable_Disease_Mortality must be set to 1.

Possible values are:

DAILY_MORTALITY

Calculated at every time step.

MORTALITY_AFTER_INFECTIOUS

Calculated once at the end of the disease duration.

 
{
    "Mortality_Time_Course": "MORTALITY_AFTER_INFECTIOUS"
}

x_Other_Mortality

float

0

3.40E+38

1

Scale factor for mortality from causes other than the disease being simulated. Base mortality is provided by the demographics file (see Complex distributions parameters). Enable_Natural_Mortality must be set to 1.

 
{
    "x_Other_Mortality": 1
}
Output settings

The following parameters configure whether or not output reports are created for the simulation, such as reports detailing spatial or demographic data at each time step. By default, the InsetChart is always created.

The following figures are examples for the parameter Report_HIV_Period.

When Report_HIV_Period is set to a value that is less than the Simulation_Timestep, a record will be written during the next time step after the reported period. More than one period may occur before the next time step.

_images/Report_HIV_Period-timeline-example1.png

Figure 1: Report_HIV_Period < **Simulation_Timestep

When Report_HIV_Period is greater than Simulation_Timestep, a record will be written during the next time step after the period occurs. This means that a record may not be written at all time steps.

_images/Report_HIV_Period-timeline-example2.png

Figure 2: Report_HIV_Period > **Simulation_Timestep

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Custom_Coordinator_Events

array of strings

NA

NA

NA

The list of valid, user-defined events for Event Coordinators that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Custom_Individual_Events

array of strings

NA

NA

NA

The list of valid, user-defined events that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note

This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Individual_Events": [
        "Individual_Event_1",
        "Individual_Event_2",
        "Individual_Event_3"
    ]
}

Custom_Node_Events

array of strings

NA

NA

NA

The list of valid, user-defined events for nodes that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note

This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2",
        "Node_Event_3"
    ]
}

Custom_Reports_Filename

string

NA

NA

UNINITIALIZED STRING

The name of the file containing custom report configuration parameters. Omitting this parameter or setting it to RunAllCustomReports will load all reporters found that are valid for the given simulation type. The file must be in JSON format.

 
{
    "Custom_Reports_Filename": "custom_reports.json"
}

Enable_Default_Reporting

boolean

0

1

1

Controls whether or not the default InsetChart.json report is created.

 
{
    "Enable_Default_Reporting": 1
}

Enable_Demographics_Reporting

boolean

0

1

1

Controls whether or not demographic summary data and age-binned reports are outputted to file.

 
{
    "Enable_Demographics_Reporting": 1
}

Enable_Property_Output

boolean

0

1

0

Controls whether or not to create property output reports, which detail groups as defined in IndividualProperties in the demographics file (see NodeProperties and IndividualProperties parameters). When there is more than one property type, the report will display the channel information for all combinations of the property type groups.

 
{
    "Enable_Property_Output": 1
}

Enable_Spatial_Output

boolean

0

1

0

Controls whether or not spatial output reports are created. If set to true (1), spatial output reports include all channels listed in the parameter Spatial_Output_Channels.

Note

Spatial output files require significant processing time and disk space.

 
{
    "Enable_Spatial_Output": 1,
    "Spatial_Output_Channels": [
        "Prevalence",
        "New_Infections"
    ]
}

Report_Coital_Acts

boolean

0

1

0

Set to true (1) to enable or to false (0) to disable the RelationshipConsummatedReport.csv output report.

 
{
    "Report_Coital_Acts": 1
}

Report_Coordinator_Event_Recorder

boolean

0

1

0

Enables or disables the ReportCoordinatorEventRecorder.csv output report for coordinator events. When enabled (set to 1) reports will be generated for the broadcasted valid coordinator events, as specified in Report_Coordinator_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Report_Coordinator_Event_Recorder_Events

array of strings

NA

NA

NA

The list of events to include or exclude in the ReportCoordinatorEventRecorder.csv output report, based on how Report_Coordinator_Event_Recorder_Ignore_Events_In_List is set. This list must not be empty and is dependent upon Report_Coordinator_Event_Recorder being enabled. In addition, the events must be defined in Customer_Coordinator_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Report_Coordinator_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the events listed in the Report_Coordinator_Event_Recorder_Events array will be included in the ReportCoordinatorEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder": 1,
    "Report_Coordinator_Event_Recorder_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ],
    "Report_Coordinator_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder

boolean

0

1

0

Set to true (1) to enable or to false (0) to disable the ReportEventRecorder.csv output report that lists individual events in the simulation. See Event list for a list of all possible built-in events that will be recorded in the output when enabled.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Events

array

NA

NA

The list of events to include or exclude in the ReportEventRecorder.csv output report, based on how Report_Event_Recorder_Ignore_Events_In_List is set. See Event list for a list of all possible built-in events. You can also define events in Custom_Individual_Events. The list cannot be empty.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the events listed in the Report_Event_Recorder_Events array will be included in the ReportEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty.

Value

Events array

Output file

0

No events

No events

0

One or more events

Only the listed events.

1

No events

All events occurring in the simulation.

1

One or more events

All simulation events occurring in the simulation, except for those listed.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Individual_Properties

array of strings

NA

NA

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added as additional columns to the output report. Individual’s IP value will be added to the (key) column at the time of the event.

 
{
    "Report_Event_Recorder_Individual_Properties": [
        "Accessibility",
        "Risk"
    ]
}

Report_Event_Recorder_Start_Day

float

0

3.40282e+38

0

The day of the simulation to start collecting data.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_End_Day

float

0

3.40282e+38

3.40282e+38

The day of the simulation to stop collecting data.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Node_IDs_Of_Interest

array of integers

0

2.14748e+09

[]

Data will be collected for the nodes in this list.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Node_IDs_Of_Interest": [ 2, 7 ],
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Min_Age_Years

float

0

9.3228e+35

0

Minimum age in years of people to collect data on.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Min_Age_Years": 5,
    "Report_Event_Recorder_Max_Age_Years": 10,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Max_Age_Years

float

0

9.3228e+35

9.3228e+35

Maximum age in years of people to collect data on.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Min_Age_Years": 5,
    "Report_Event_Recorder_Max_Age_Years": 10,
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Must_Have_IP_Key_Value

string

NA

NA

(empty string)

A Key:Value pair that the individual must have in order to be included. Empty string means to not include IPs in the selection criteria.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Min_Age_Years": 5,
    "Report_Event_Recorder_Max_Age_Years": 10,
    "Report_Event_Recorder_Must_Have_IP_Key_Value": "Risk:LOW",
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Event_Recorder_Must_Have_Intervention

string

NA

NA

(empty string)

The name of the intervention that the person must have in order to be included. Empty string means to not include interventions in the selection criteria.

 
{
    "Report_Event_Recorder": 1,
    "Report_Event_Recorder_Start_Day": 365,
    "Report_Event_Recorder_End_Day": 730,
    "Report_Event_Recorder_Min_Age_Years": 5,
    "Report_Event_Recorder_Max_Age_Years": 10,
    "Report_Event_Recorder_Must_Have_IP_Key_Value": "Risk:LOW",
    "Report_Event_Recorder_Must_Have_Intervention": "UsageDependentBednet",
    "Report_Event_Recorder_Events": [
        "VaccinatedA",
        "VaccineExpiredA",
        "VaccinatedB",
        "VaccineExpiredB"
    ],
    "Report_Event_Recorder_Ignore_Events_In_List": 0
}

Report_HIV_ART

boolean

0

1

0

Set to true (1) to enable or to false (0) to disable the ReportHIVART.csv output report.

 
{
    "Report_HIV_ART": 0
}

Report_HIV_ByAgeAndGender

boolean

0

1

0

Set to true (1) to enable or to false (0) to disable the ReportHIVByAgeAndGener.csv output report.

 
{
    "Report_HIV_ByAgeAndGender": 1
}

Report_HIV_ByAgeAndGender_Add_Concordant_Relationships

boolean

0

1

0

When set to true (1), a ‘concordant’ column for each relationship type, as defined with the Society parameter in the demographics file, is included in the ReportHIVByAgeAndGender.csv output report file. Each ‘concordant’ column will include the number of concordant relationships, where both partners have the same disease status.

 
{
    "Report_HIV_ByAgeAndGender_Add_Concordant_Relationships": 1
}

Report_HIV_ByAgeAndGender_Add_Relationships

boolean

0

1

0

Sets whether or not the ReportHIVByAgeAndGender.csv output file will contain data by relationship type on population currently in a relationship and ever in a relationship. A sum of those in two or more partnerships and a sum of the lifetime number of relationships in each bin will be included.

 
{
    "Report_HIV_ByAgeAndGender_Add_Relationships": 1
}

Report_HIV_ByAgeAndGender_Add_Transmitters

boolean

0

1

0

When set to to true (1), the ‘transmitters’ column is included in the output report. For a given row, ‘Transmitters’ indicates how many people that have transmitted the disease meet the specifications of that row.

 
{
    "Report_HIV_ByAgeAndGender_Add_Transmitters": 1
}

Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data

array of floats

-3.40282e+38

3.40282e+38

1

This array of floats allows the user to define the age bins used to stratify the report by age. Each value defines the minimum value of that bin, while the next value defines the maximum value of the bin. The maximum number of age bins is 100. For example, if you had:

“Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data” : [ 0, 10, 20, 50, 100 ]

The report would have the following age bins: From 0 up to (but not including) 10, from 10 up to (but not including) 20, from 20 up to (but not including) 50, from 50 up to (but not including) 100, and 100 and over.

If no values are specified in the array, then the output report will have no age binning.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data": [
        0,
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15,
        16,
        17,
        18,
        19,
        20,
        21,
        22,
        23,
        24,
        25,
        26,
        27,
        28,
        29,
        30,
        31,
        32,
        33,
        34,
        35,
        36,
        37,
        38,
        39,
        40,
        41,
        42,
        43,
        44,
        45,
        46,
        47,
        48,
        49,
        50,
        51,
        52,
        53,
        54,
        55,
        56,
        57,
        58,
        59,
        60,
        61,
        62,
        63,
        64,
        65,
        66,
        67,
        68,
        69,
        70,
        71,
        72,
        73,
        74,
        75,
        76,
        77,
        78,
        79,
        80,
        81,
        82,
        83,
        84,
        85,
        86,
        87,
        88,
        89,
        90,
        91,
        92,
        93,
        94,
        95,
        96,
        97,
        98,
        99
    ]
}

Report_HIV_ByAgeAndGender_Collect_Circumcision_Data

boolean

0

1

0

When set to 1, the ReportHIVByAgeAndGender.csv output report will have separate rows for those who do or do not have the MaleCircumcision intervention and an additional column with 0 and 1 indicating whether the row corresponds to those who are or are not circumcised. Setting this to 1 doubles the number of rows in ReportHIVByAgeAndGender.csv.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Circumcision_Data": 0
}

Report_HIV_ByAgeAndGender_Collect_Gender_Data

boolean

0

1

0

Controls whether or not the report is stratified by gender; to enable gender stratification, set to true (1).

 
{
    "Report_HIV_ByAgeAndGender_Collect_Gender_Data": 1
}

Report_HIV_ByAgeAndGender_Collect_HIV_Data

boolean

0

1

0

When set to 1, data in the ReportHIVByAgeAndGender.csv output report will be stratified by those who do or do not have HIV. Setting this to 1 doubles the number of rows in ReportHIVByAgeAndGender.csv.

 
{
    "Report_HIV_ByAgeAndGender_Collect_HIV_Data": 1
}

Report_HIV_ByAgeAndGender_Collect_Intervention_Data

array of strings

NA

NA

NA

Stratifies the population by adding a column of 0s and 1s depending on whether or not the person has the indicated intervention. This only works for interventions that remain with a person for a period of time, such as ART, VMMC, vaccine/PrEP, or a delay state in the cascade of care. You can name the intervention by adding a parameter Intervention_Name in the campaign file, and then give this parameter the same Intervention_Name. This allows you to have multiple types of vaccines, VMMCs, etc., but to only stratify on the type you want.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Intervention_Data": [
        "ART_Intervention",
        "PrEP_Intervention"
    ]
}

Report_HIV_ByAgeAndGender_Collect_IP_Data

boolean

0

1

0

When set to 1, the ReportHIVByAgeAndGender.csvoutput report will have separate rows for those with different IndividualProperties values and an additional column for each property indicating which row corresponds to which value of that property. Setting this to 1 typically increases by severalfold the number of rows in ReportHIVByAgeAndGender.csv.

 
{
    "Report_HIV_ByAgeAndGender_Collect_IP_Data": 0
}

Report_HIV_ByAgeAndGender_Collect_On_Art_Data

boolean

0

1

0

Controls whether or not the output report is stratified by those people who are on ART and those who are not. Set to true (1) to enable stratification by ART status.

 
{
    "Report_HIV_ByAgeAndGender_Collect_On_Art_Data": 1
}

Report_HIV_ByAgeAndGender_Event_Counter_List

array of strings

NA

NA

NA

A list of columns to add to the ReportHIVByAgeAndGender.csv output files counting the number of times an intervention with the corresponding Distributed_Event_Trigger has been distributed. Note that the interventions will be specified in the campaign file.

 
{
    "Report_HIV_ByAgeAndGender_Event_Counter_List": [
        "Reduced_Acquire_Lowest",
        "Reduced_Acquire_Medium",
        "Reduced_Acquire_Low",
        "Reduced_Acquire_Highest_Not_Duplicated"
    ]
}

Report_HIV_ByAgeAndGender_Has_Intervention_With_Name

string

NA

NA

“”

This parameter will be deprecated. We recommend you use Report_HIV_ByAgeAndGender_Collect_Intervention_Data instead.

 
{
    "Report_HIV_ByAgeAndGender_Has_Intervention_With_Name": "VaccineA"
}

Report_HIV_ByAgeAndGender_Start_Year

float

1900

2200

1900

The beginning calendar year that will be collected by the ReportHIVByAgeAndGender.csv report.

 
{
    "Report_HIV_ByAgeAndGender_Start_Year": 1962,
    "Report_HIV_ByAgeAndGender_Stop_Year": 1978
}

Report_HIV_ByAgeAndGender_Stop_Year

float

1900

2200

2200

The ending calendar year that will be collected by the HIVByAgeAndGender.csv report.

 
{
    "Report_HIV_ByAgeAndGender_Start_Year": 1962,
    "Report_HIV_ByAgeAndGender_Stop_Year": 1978
}

Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4

boolean

0

1

0

When set to 1, the ReportHIVByAgeAndGender.csv output file will separate the count of the number of infected individuals by CD4 stratum. When set to 0, the number of infected individuals are aggregated into one column regardless of CD4 count.

 
{
    "Report_HIV_ByAgeAndGender_Stratify_Infected_By_CD4": 0
}

Report_HIV_Event_Channels_List

array of strings

NA

NA

NA

This is the list of events included in the InsetChart report. If events are specified with this parameter, the InsetChart will include a channel for each event listed. If no events are listed, a “Number of Events” channel will display the total number of all events that occurred during the simulation.

 
{
    "Report_HIV_Event_Channels_List": [
        "NewInfectionEvent",
        "HIVNeedsHIVTest",
        "HIVPositiveHIVTest",
        "HIVNegativeHIVTest",
        "HIVDiagnosedEligibleForART",
        "HIVSymptomatic",
        "DiseaseDeaths",
        "NonDiseaseDeaths",
        "Births"
    ]
}

Report_HIV_Infection

boolean

0

1

0

Enables or disables the ReportHIVInfection.csv output report.

 
{
    "Report_HIV_Infection": 0
}

Report_HIV_Infection_Start_Year

float

1900

2200

1900

The beginning calendar year that will be collected by the ReportHIVInfection.csv output report. Report_HIV_Infection must be set to 1.

 
{
    "Report_HIV_Infection_Start_Year": 1900
}

Report_HIV_Infection_Stop_Year

float

1900

2200

2200

The ending calendar year that will be collected by the ReportHIVInfection.csv output report. Report_HIV_Infection must be set to 1.

 
{
    "Report_HIV_Infection_Stop_Year": 2100
}

Report_HIV_Mortality

boolean

0

1

0

Enables or disables the HIVMortality.csv (disease and non-disease deaths) output report.

 
{
    "Report_HIV_Mortality": 0
}

Report_HIV_Period

float

30

36500

730

The number of days between records in the HIV_By_Age_And_Gender output report. Output data will only be recorded during a time step, so if Report_HIV_Period is set to a value less than the value set for Simulation_Timestep, more than one period may occur before the next time step. When Report_HIV_Period is greater than the value set for Simulation_Timestep, a record may not be written during each time step. Note that the number of days between records is half the time specified by this parameter. For example, if Report_HIV_Period is set to 40, the actual time between records is 20 days. For best results, use integers for this value.

 
{
    "Report_HIV_Period": 365
}

Report_Node_Event_Recorder

boolean

0

1

0

Enables or disables the ReportNodeEventRecorder.csv output report. When enabled (set to 1) reports will be generated for the broadcasted valid node events, as specified in Report_Node_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ]
}

Report_Node_Event_Recorder_Events

array of strings

NA

NA

NA

The list of node events to include or exclude in the ReportNodeEventRecorder.csv output report, based on how Report_Node_Event_Recorder_Ignore_Events_In_List is set.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Node_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the node events listed in the Report_Node_Event_Recorder_Events array will be included in the ReportNodeEventRecorder.csv output report. If set to true (1), only the node events listed in the array will be excluded, and all other node events will be included. If you want to return all node events from the simulation, leave the node events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

Value

Events array

Output file

0

No events

No events

0

One or more events

Only the listed events.

1

No events

All events occurring in the simulation.

1

One or more events

All simulation events occurring in the simulation, except for those listed.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Node_Event_Recorder_Node_Properties

array of strings

NA

NA

[]

Specifies an array of (optional) node property keys, as defined in NodeProperties in the demographics file, to be added as additional columns to the ReportNodeEventRecorder.csv output report.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0,
    "Report_Node_Event_Recorder_Node_Properties": [
        "Geographic"
    ]
}

Report_Node_Event_Recorder_Stats_By_IPs

array of strings

NA

NA

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the ReportNodeEventRecorder.csv output report. For each key:value pair there will be two additional columns (Key:Value:NumIndividuals, Key:Value:NumInfected) added to the report. For example, with a Risk property key assigned the values of LOW and HIGH there would then be four additional columns (Risk:LOW:NumIndividuals, Risk:LOW:NumInfected, Risk:HIGH:NumIndividuals, Risk:HIGH:NumInfected). An empty array equals no additional columns added.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder": 1,
    "Report_Node_Event_Recorder_Events": [
        "Node_Event_1",
        "Node_Event_2"
    ],
    "Report_Node_Event_Recorder_Ignore_Events_In_List": 0,
    "Report_Node_Event_Recorder_Node_Properties": [
        "Geographic"
    ],
    "Report_Node_Event_Recorder_Stats_By_IPs": [
        "Risk"
    ]
}

Report_Relationship_End

boolean

0

1

0

Enables or disables the RelationshipEnd.csv output report. For HIV simulations, there will be no additional columns.

 
{
    "Report_Relationship_End": 0
}

Report_Relationship_Start

boolean

0

1

0

Enables or disables the RelationshipStart.csv output report. For HIV simulations, there will be some additional columns.

 
{
    "Report_Relationship_Start": 0
}

Report_Relationship_Start_Individual_Properties

array of strings

NA

NA

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the RelationshipStart.csv output report.

 
{
    "Report_Relationship_Start_Individual_Properties": [
        "CascadeState",
        "Risk",
        "HasSTI"
    ]
}

Report_Surveillance_Event_Recorder

boolean

0

1

0

Enables or disables the ReportSurveillanceEventRecorder.csv output report. When enabled (set to 1) reports will be generated for the broadcasted valid coordinator events, as specified in Report_Surveillance_Event_Recorder_Events.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ]
}

Report_Surveillance_Event_Recorder_Events

array of strings

NA

NA

NA

The list of events to include or exclude in the ReportSurveillanceEventRecorder.csv output report, based on how Report_Surveillance_Event_Recorder_Ignore_Events_In_List is set. This list must not be empty and is dependent upon Report_Surveillance_Event_Recorder being enabled.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ]
}

Report_Surveillance_Event_Recorder_Ignore_Events_In_List

boolean

0

1

0

If set to false (0), only the events listed in the Report_Surveillance_Event_Recorder_Events array will be included in the ReportSurveillanceEventRecorder.csv output report. If set to true (1), only the events listed in the array will be excluded, and all other events will be included. If you want to return all events from the simulation, leave the events array empty.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

Value

Events array

Output file

0

No events

No events

0

One or more events

Only the listed events.

1

No events

All events occurring in the simulation.

1

One or more events

All simulation events occurring in the simulation, except for those listed.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder_Ignore_Events_In_List": 0
}

Report_Surveillance_Event_Recorder_Stats_By_IPs

array of strings

NA

NA

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the ReportSurveillanceEventRecorder.csv output report. For each key:value pair there will be two additional columns (Key:Value:NumIndividuals, Key:Value:NumInfected) added to the report. For example, with a Risk property key assigned the values of LOW and HIGH there would then be four additional columns (Risk:LOW:NumIndividuals, Risk:LOW:NumInfected, Risk:HIGH:NumIndividuals, Risk:HIGH:NumInfected). An empty array equals no additional columns added.

 
{
    "Custom_Coordinator_Events": [
        "Start_ACF",
        "Start_SIA_2",
        "Start_SIA_4",
        "Ind_Start_SIA_2",
        "Ind_Start_SIA_4",
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder": 1,
    "Report_Surveillance_Event_Recorder_Events": [
        "Respond_To_Surveillance"
    ],
    "Report_Surveillance_Event_Recorder_Stats_By_IPs": []
}

Report_Transmission

boolean

0

1

0

Enables or disables the TransmissionReport.csv output report. For HIV simulations, there will be some additional columns.

 
{
    "Report_Transmission": 0
}

Report_Transmission_Individual_Properties

array of strings

NA

NA

[]

Specifies an array of (optional) individual property keys, as defined in IndividualProperties in the demographics file, to be added to the TransmissionReport.csv output report.

 
{
    "Report_Transmission_Individual_Properties": [
        "Accessibility",
        "InterventionStatus"
    ]
}

Spatial_Output_Channels

array of strings

NA

NA

[]

An array of channel names for spatial output by node and time step. The data from each channel will be written to a separate binary file. Enable_Spatial_Output must be set to true (1). Possible values are:

Air_Temperature

Data related to air temperature.

Births

Data related to the number of births.

Campaign_Cost

Data related to the costs of a campaign.

Disease_Deaths

Data related to the number of deaths due to disease.

Human_Infectious_Reservoir

Data related to the total infectiousness of the population.

Infection_Rate

Data related to infection rates.

Land_Temperature

Data related to the average land temperature over all nodes.

New_Infections

Data related to the presence of new infections.

New_Reported_Infections

Data related to the presence of reported new infections.

Population

Data related to the total population in the simulation.

Prevalence

Data related to the fraction of the population that is infected.

Rainfall

Data related to the presence of rainfall.

Relative_Humidity

Data related to the presence of relative humidity.

 
{
    "Spatial_Output_Channels": [
        "Prevalence",
        "New_Infections"
    ]
}
Population dynamics

The following parameters determine characteristics related to population dynamics, such as age distribution, births, deaths, and gender. The values set here generally interact closely with values in the demographics file.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Initialization_Distribution_Type

enum

NA

NA

DISTRIBUTION_OFF

The method for initializing the age distribution in the simulated population. Possible values are:

DISTRIBUTION_OFF

All individuals default to age 20 years old.

DISTRIBUTION_SIMPLE

Individual ages are drawn from a distribution whose functional form is specified in the demographics file using the IndividualAttributes simple Age distribution parameters.

DISTRIBUTION_COMPLEX

Individual ages are drawn from a piecewise linear function specified in the demographics file complex distribution parameters.

 
{
    "Age_Initialization_Distribution_Type": "DISTRIBUTION_SIMPLE"
}

Birth_Rate_Boxcar_Forcing_Amplitude

float

0

3.40E+38

0

Fractional increase in birth rate during high birth season when Birth_Rate_Time_Dependence is set to ANNUAL_BOXCAR_FUNCTION.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "ANNUAL_BOXCAR_FUNCTION",
    "Birth_Rate_Boxcar_Forcing_Amplitude": 0.1
}

Birth_Rate_Boxcar_Forcing_End_Time

float

0

365

0

Day of the year when the high birth rate season ends when Birth_Rate_Time_Dependence is set to ANNUAL_BOXCAR_FUNCTION.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "ANNUAL_BOXCAR_FUNCTION",
    "Birth_Rate_Boxcar_Forcing_End_Time": 220
}

Birth_Rate_Boxcar_Forcing_Start_Time

float

0

365

0

Day of the year when the high birth rate season begins when Birth_Rate_Time_Dependence is set to ANNUAL_BOXCAR_FUNCTION.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "ANNUAL_BOXCAR_FUNCTION",
    "Birth_Rate_Boxcar_Forcing_Start_Time": 130
}

Birth_Rate_Dependence

enum

NA

NA

FIXED_BIRTH_RATE

The method used to modify the value set in BirthRate in the demographics file (see NodeAttributes parameters). Possible values are:

NONE

Births are not allowed during the simulation, even if Enable_Birth is set to true (1).

FIXED_BIRTH_RATE

The absolute rate at which new individuals are born, as set by BirthRate.

POPULATION_DEP_RATE

Scales the node population to determine the birth rate. If BirthRate is greater than 0.005, a value of 2% per year (0.02/365) is used instead.

DEMOGRAPHIC_DEP_RATE

Scales the female population within fertility age ranges (15-44 years) to determine the birth rate. If BirthRate is greater than 0.005, a value of 1 child every 8 years of fertility [1/8/365(~0.000342)] is used instead.

INDIVIDUAL_PREGNANCIES

Scales the female population within fertility age ranges (15-44 years) to determine the birth rate, but pregnancies are assigned on an individual basis and result in a 40-week pregnancy for a specific individual with a birth at the end.

INDIVIDUAL_PREGNANCIES_BY_AGE_AND_YEAR

Similar to INDIVIDUAL_PREGNANCIES, but determines the rate based on the FertilityDistribution (in IndividualAttributes), using the individual’s age and the year of the simulation.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Dependence": "POPULATION_DEP_RATE"
}

Birth_Rate_Sinusoidal_Forcing_Amplitude

float

0

1

0

The amplitude of sinusoidal variations in birth rate when Birth_Rate_Time_Dependence is set to SINUSOIDAL_FUNCTION_OF_TIME.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "SINUSOIDAL_FUNCTION_OF_TIME",
    "Birth_Rate_Sinusoidal_Forcing_Amplitude": 0.1
}

Birth_Rate_Sinusoidal_Forcing_Phase

float

0

365

0

The phase of sinusoidal variations in birth rate. Birth_Rate_Time_Dependence must be set to SINUSOIDAL_FUNCTION_OF_TIME.

 
{
    "Birth_Rate_Sinusoidal_Forcing_Phase": 20
}

Birth_Rate_Time_Dependence

enum

NA

NA

NONE

A scale factor for BirthRate that allows it to be altered by time or season. Enable_Birth must be set to true (1). Possible values are:

NONE

Birth rate does not vary by time.

SINUSOIDAL_FUNCTION_OF_TIME

Allows birth rate to be time-dependent, following a sinusoidal shape defined by \(1 + \sin \text{Birth\_Rate\_Sinusoidal\_Forcing\_Amplitude} \times \sin(2 \pi \times (\text{day} - \sin \text{Birth\_Rate\_Sinusoidal\_Forcing\_Phase})/365)\). Set Birth_Rate_Sinusoidal_Forcing_Amplitude and Birth_Rate_Sinusoidal_Forcing_Phase.

ANNUAL_BOXCAR_FUNCTION

Allows birth rate to follow a boxcar function. The scale factor will be equal to 1 except for a single interval in which it is equal to a given constant equal to 1 + Birth_Rate_Boxcar_Forcing_Amplitude. Set Birth_Rate_Boxcar_Forcing_Amplitude, Birth_Rate_Boxcar_Forcing_End_Time, and Birth_Rate_Boxcar_Forcing_Start_Time.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "ANNUAL_BOXCAR_FUNCTION"
}

Death_Rate_Dependence

enum

NA

NA

NOT_INITIALIZED

Determines how likely individuals are to die from natural, non-disease causes. Enable_Natural_Mortality must be set to 1. Possible values are:

NOT_INITIALIZED

The daily mortality rate is 0, and no one dies from non-disease related causes.

NONDISEASE_MORTALITY_BY_AGE_AND_GENDER

The individual’s age and gender are taken into account to determine the daily mortality rate.

NONDISEASE_MORTALITY_BY_YEAR_AND_AGE_FOR_EACH_GENDER

Gender, age, and year, are all taken into account to determine the daily mortality rate.

Properties, rates, and bin sizes can be set for non-disease mortality for each gender in the demographics file (see Complex distributions parameters).

 
{
    "Death_Rate_Dependence": "NONDISEASE_MORTALITY_BY_AGE_AND_GENDER"
}

Default_Geography_Initial_Node_Population

integer

0

1000000

1000

When using the built-in demographics for default geography, the initial number of individuals in each node. Note that the built-in demographics feature does not represent a real geographical location and is mostly used for testing. Enable_Demographics_Builtin must be set to true (1).

 
{
    "Enable_Demographics_Builtin": 1,
    "Default_Geography_Initial_Node_Population": 1000,
    "Default_Geography_Torus_Size": 3
}

Demographics_Filenames

array of strings

NA

NA

An array of the paths to demographics files containing information on the identity and demographics of the region to simulate. The files must be in .json format. Note that this parameter is only required when Enable_Demographics_Builtin is set to 0.

 
{
    "Demographics_Filenames": [
        "Namawala_single_node_demographics.json",
        "Namawala_demographics_overlay.json"
    ]
}

Enable_Aging

boolean

0

1

1

Controls whether or not individuals in a population age during the simulation. Enable_Vital_Dynamics must be set to true (1).

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Aging": 1
}

Enable_Birth

boolean

0

1

1

Controls whether or not individuals will be added to the simulation by birth. Enable_Vital_Dynamics must be set to true (1). If you want new individuals to have the same intervention coverage as existing individuals, you must add a BirthTriggeredIV to the campaign file.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1
}

Enable_Demographics_Birth

boolean

0

1

0

Controls whether or not newborns have disease risk drawn from a distribution; uniform disease risk if false. Enable_Birth, Enable_Demographics_Risk, and Enable_Vital_Dynamics must be set to true (1).

 
{
    "Enable_Birth": 1,
    "Enable_Demographics_Birth": 1,
    "Enable_Vital_Dynamics": 1
}

Enable_Demographics_Builtin

boolean

0

1

0

Controls whether or not built-in demographics for default geography will be used. Note that the built-in demographics feature does not represent a real geographical location and is mostly used for testing. Set to true (1) to define the initial population and number of nodes using Default_Geography_Initial_Node_Population and Default_Geography_Torus_Size. Set to false (0) to use demographics input files defined in Demographics_Filenames.

 
{
    "Enable_Demographics_Builtin": 1,
    "Default_Geography_Initial_Node_Population": 1000,
    "Default_Geography_Torus_Size": 3
}

Enable_Vital_Dynamics

boolean

0

1

1

Controls whether or not births and deaths occur in the simulation. Births and deaths must be individually enabled and set.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Death_Rate_Dependence": "NOT_INITIALIZED",
    "Base_Mortality": 0.002
}

Minimum_Adult_Age_Years

float

0

3.40E+38

15

The age, in years, after which an individual is considered an adult. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP.

 
{
    "Minimum_Adult_Age_Years": 17
}

Population_Density_Infectivity_Correction

enum

NA

NA

CONSTANT_INFECTIVITY

Correction to alter infectivity by population density set in the Population_Density_C50 parameter. Measured in people per square kilometer. Possible values are:

  • CONSTANT_INFECTIVITY

  • SATURATING_FUNCTION_OF_DENSITY

Note

Sparsely populated areas have a lower infectivity, while densely populated areas have a higher infectivity, which rises to saturate at the Base_Infectivity value.

 
{
    "Population_Density_Infectivity_Correction": "SATURATING_FUNCTION_OF_DENSITY"
}

Population_Scale_Type

enum

NA

NA

USE_INPUT_FILE

The method to use for scaling the initial population specified in the demographics input file. Possible values are:

USE_INPUT_FILE

Turns off population scaling and uses InitialPopulation in the demographics file (see NodeAttributes parameters).

FIXED_SCALING

Enables Base_Population_Scale_Factor.

 
{
    "Population_Scale_Type": "FIXED_SCALING"
}

Report_HIV_ByAgeAndGender_Add_Transmitters

boolean

0

1

0

When set to to true (1), the ‘transmitters’ column is included in the output report. For a given row, ‘Transmitters’ indicates how many people that have transmitted the disease meet the specifications of that row.

 
{
    "Report_HIV_ByAgeAndGender_Add_Transmitters": 1
}

Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data

array of floats

-3.40282e+38

3.40282e+38

1

This array of floats allows the user to define the age bins used to stratify the report by age. Each value defines the minimum value of that bin, while the next value defines the maximum value of the bin. The maximum number of age bins is 100. For example, if you had:

“Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data” : [ 0, 10, 20, 50, 100 ]

The report would have the following age bins: From 0 up to (but not including) 10, from 10 up to (but not including) 20, from 20 up to (but not including) 50, from 50 up to (but not including) 100, and 100 and over.

If no values are specified in the array, then the output report will have no age binning.

 
{
    "Report_HIV_ByAgeAndGender_Collect_Age_Bins_Data": [
        0,
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15,
        16,
        17,
        18,
        19,
        20,
        21,
        22,
        23,
        24,
        25,
        26,
        27,
        28,
        29,
        30,
        31,
        32,
        33,
        34,
        35,
        36,
        37,
        38,
        39,
        40,
        41,
        42,
        43,
        44,
        45,
        46,
        47,
        48,
        49,
        50,
        51,
        52,
        53,
        54,
        55,
        56,
        57,
        58,
        59,
        60,
        61,
        62,
        63,
        64,
        65,
        66,
        67,
        68,
        69,
        70,
        71,
        72,
        73,
        74,
        75,
        76,
        77,
        78,
        79,
        80,
        81,
        82,
        83,
        84,
        85,
        86,
        87,
        88,
        89,
        90,
        91,
        92,
        93,
        94,
        95,
        96,
        97,
        98,
        99
    ]
}

Report_HIV_ByAgeAndGender_Collect_Gender_Data

boolean

0

1

0

Controls whether or not the report is stratified by gender; to enable gender stratification, set to true (1).

 
{
    "Report_HIV_ByAgeAndGender_Collect_Gender_Data": 1
}

x_Base_Population

float

0

3.40E+38

1

Scale factor for InitialPopulation in the demographics file (see NodeAttributes parameters). If Population_Scale_Type is set to FIXED_SCALING, the initial simulation population is uniformly scaled over the entire area to adjust for historical or future population density.

 
{
    "x_Base_Population": 0.0001
}

x_Birth

float

0

3.40E+38

1

Scale factor for birth rate, as provided by the demographics file (see NodeAttributes parameters). Enable_Birth must be set to 1.

 
{
    "x_Birth": 1
}
Relationships and pair formation

The following parameters determine how individuals form relationships, such as sexual behavior, relationship duration, age gaps, and any gender differences in those characteristics.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Coital_Dilution_Factor_2_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly two current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_2_Partners": 0.5
}

Coital_Dilution_Factor_3_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly three current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_3_Partners": 0.33
}

Coital_Dilution_Factor_4_Plus_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly three current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_4_Partners": 0.45
}

Enable_Coital_Dilution

boolean

0

1

1

Controls whether or not coital dilution will occur.

 
{
    "Enable_Coital_Dilution": 1
}

Min_Days_Between_Adding_Relationships

float

0

365

60

The minimum number of days between adding two consecutive relationships as a means to control concurrency. The constraint does not apply if an individual breaks an existing relationship.

 
{
    "Min_Days_Between_Adding_Relationships": 1
}

PFA_Burnin_Duration_In_Days

float

1

3.40E+38

365000

The number of days to continue tuning the pair formation rates. After this duration, the rates will remain at the last rate value calculated.

 
{
    "PFA_Burnin_Duration_In_Days": 5475
}

PFA_Cum_Prob_Selection_Threshold

float

0

1

0.2

This parameter serves to minimize the extent to which relationships with unlikely age gaps are formed. These unlikely relationships could be generated due to lack of diversity in the PFA. Within the algorithm, males pick from amongst the available females by age bin, weighted by the conditional of the joint_probability matrix given the male age bin. If the sum of the probabilities in the female age bins that are not empty is below this threshold, the male will wait till the next update. Setting this parameter to a value near 1 dramatically increases the delay that individuals will experience in seeking relationships. Setting this parameter to 0 disables the feature.

 
{
    "PFA_Cum_Prob_Selection_Threshold": 0.4
}

Report_HIV_ByAgeAndGender_Add_Concordant_Relationships

boolean

0

1

0

When set to 1, a Concordant column for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL) is included in the output report. These contain totals for each relationship of each type where both partners have the same HIV status.

 
{
    "Report_HIV_ByAgeAndGender_Add_Concordant_Relationships": 1
}

Report_HIV_ByAgeAndGender_Add_Relationships

boolean

0

1

0

When set to 1, the report will contain data on the population currently in a relationship and ever in a relationship for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL), eight columns total. Additionally, columns containing a sum of individuals in two or more partnerships (Has Concurrent Partners) and a sum of the lifetime number of relationships (Lifetime Partners) will be included.

 
{
    "Report_HIV_ByAgeAndGender_Add_Relationships": 1
}

Sexual_Debut_Age_Female_Weibull_Heterogeneity

float

0

50

20

The inverse shape of the Weibull distribution for female debut age.

 
{
    "Sexual_Debut_Age_Female_Weibull_Heterogeneity": 0.05
}

Sexual_Debut_Age_Female_Weibull_Scale

float

0

50

16

The scale term of the Weibull distribution for female debut age.

 
{
    "Sexual_Debut_Age_Female_Weibull_Scale": 15.919654846191
}

Sexual_Debut_Age_Male_Weibull_Heterogeneity

float

0

50

20

The inverse shape of the Weibull distribution for male debut age.

 
{
    "Sexual_Debut_Age_Male_Weibull_Heterogeneity": 0.05
}

Sexual_Debut_Age_Male_Weibull_Scale

float

0

50

16

The scale term of the Weibull distribution for male debut age.

 
{
    "Sexual_Debut_Age_Male_Weibull_Scale": 16.946729660034
}

Sexual_Debut_Age_Min

float

0

3.40E+38

13

The minimum age at which individuals become eligible to form sexual relationships.

 
{
    "Sexual_Debut_Age_Min": 13
}
Sampling

The following parameters determine how a population is sampled in the simulation. While you may want every agent (individual object) to represent a single person, you can often optimize CPU time with without degrading the accuracy of the simulation but having an agent represent multiple people. The sampling rate may be adapted to have a higher or lower sampling rate for particular regions or age groups.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Individual_Sample_Rate

float

0.001

1

1

The base rate of sampling for individuals, equal to the fraction of individuals in each node being sampled. Reducing the sampling rate will reduce the time needed to run simulations. Individual_Sampling_Type must be set to FIXED_SAMPLING or ADAPTED_SAMPLING_BY_IMMUNE_STATE.

 
{
    "Base_Individual_Sample_Rate": 0.01
}

Immune_Threshold_For_Downsampling

float

0

1

0

The threshold on acquisition immunity at which to apply immunity-dependent downsampling; individuals who are more immune than this this threshold are downsampled. A value of 1 is equivalent to full susceptibility and 0 is equivalent to full immunity. If the acquisition immunity modifier is larger than the threshold, no downsampling occurs. Individual_Sampling_Type must set to ADAPTED_SAMPLING_BY_IMMUNE_STATE.

 
{
    "Relative_Sample_Rate_Immune": 0.1,
    "Immune_Threshold_For_Downsampling": 0.5,
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_IMMUNE_STATE"
}

Individual_Sampling_Type

enum

NA

NA

TRACK_ALL

The type of individual human sampling to use, which can be used to down sample large populations, certain age groups, or the immune population that does not contribute to transmission. Possible values are:

TRACK_ALL

Each person in the population is tracked as a single Individual object with a sampling weight of 1.

FIXED_SAMPLING

Members of the population are added to the simulation with a probability of Base_Individual_Sample_Rate and sampling weight of 1 / Base_Individual_Sample_Rate. This allows a smaller set of Individual objects to represent the overall population.

ADAPTED_SAMPLING_BY_POPULATION_SIZE

For each node, a maximum number of Individual objects is tracked (set in Max_Node_Population_Samples). If the population is smaller than this number, each person is tracked with a sampling rate of 1; if the population is larger, members of the population are added to the simulation with a probability of Max_Node_Population_Samples / population and sampling weight of population / Max_Node_Population_Samples. This setting is useful for simulations over large geographic areas with large heterogeneities in population density.

ADAPTED_SAMPLING_BY_AGE_GROUP

The population is binned by age and each age bin is sampled at a different rate as defined by Sample_Rate parameters. The setting is useful for diseases in which only infants or children are relevant by allowing full sampling of these age groups while using fewer objects to represent the rest of the population.

ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE

Each node has a maximum number of Individual objects as described in ADAPTED_SAMPLING_BY_POPULATION_SIZE, but when the population grows beyond that threshold, sampling is not done at a fixed rate, but varies by age as described in ADAPTED_SAMPLING_BY_AGE_GROUP.

ADAPTED_SAMPLING_BY_IMMUNE_STATE

Individuals who have acquired immunity are sampled at a lower rate as defined by Relative_Sample_Rate_Immune and Immune_Threshold_For_Downsampling parameters. This converges with regular sampling when those parameters are set to 1 or 0, respectively.

The following example shows how to sampling immune individuals at a lower rate.

{
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_IMMUNE_STATE",
    "Immune_Threshold_For_Downsampling": 0.5,
    "Relative_Sample_Rate_Immune": 0.1
}

The following example shows how to sampling older individuals at a lower rate.

{
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_AGE_GROUP",
    "Sample_Rate_0_18mo": 1,
    "Sample_Rate_10_14": 0.5,
    "Sample_Rate_15_19": 0.3,
    "Sample_Rate_18mo_4yr": 1,
    "Sample_Rate_20_Plus": 0.2,
    "Sample_Rate_5_9": 1,
    "Sample_Rate_Birth": 1
}

Max_Node_Population_Samples

float

1

3.40E+38

30

The maximum number of individuals to track in a node. When the population exceeds this number, the sampling rate will drop according to the value set in Individual_Sampling_Type.

 
{
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_POPULATION_SIZE",
    "Max_Node_Population_Samples": 100000
}

Relative_Sample_Rate_Immune

float

0.001

1

0.1

The relative sampling rate for people who have acquired immunity through recovery or vaccination. The immune threshold at which to downsample is set by Immune_Threshold_For_Downsampling. If set to 1, this will have no effect, even if the individual’s immunity modifier is below threshold. This can be a useful sanity check while learning this feature. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_IMMUNE_STATE.

 
{
    "Relative_Sample_Rate_Immune": 0.1,
    "Immune_Threshold_For_Downsampling": 0.8,
    "Individual_Sampling_Type": "ADAPTED_SAMPLING_BY_IMMUNE_STATE"
}

Sample_Rate_0_18mo

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for infants age 0 to 18 months. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_0_18mo": 1
}

Sample_Rate_10_14

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for children age 10 to 14 years. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_10_14": 1
}

Sample_Rate_15_19

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for adolescents age 15 to 19 years. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_15_19": 1
}

Sample_Rate_18mo_4yr

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for children age 18 months to 4 years. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_18mo_4yr": 1
}

Sample_Rate_20_plus

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for adults age 20 and older. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_20_plus": 1
}

Sample_Rate_5_9

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for children age 5 to 9 years. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_5_9": 1
}

Sample_Rate_Birth

float

0.001

1000

1

For age-adapted sampling, the relative sampling rate for births. Individual_Sampling_Type must be set to ADAPTED_SAMPLING_BY_AGE_GROUP or ADAPTED_SAMPLING_BY_AGE_GROUP_AND_POP_SIZE.

 
{
    "Sample_Rate_Birth": 1
}
Scalars and multipliers

The following parameters scale or multiply values set in other areas of the configuration file or other input files. This can be especially useful for understanding the sensitivities of disease dynamics to input data without requiring modifications to those base values. For example, one might set x_Birth to a value less than 1 to simulate a lower future birth rate due to increased economic prosperity and available medical technology.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acute_Stage_Infectivity_Multiplier

float

1

100

26

The multiplier acting on Base_Infectivity to determine the per-act transmission probability of an HIV+ individual during the acute stage.

 
{
    "Acute_Stage_Infectivity_Multiplier": 3
}

AIDS_Stage_Infectivity_Multiplier

float

1

100

10

The multiplier acting on Base_Infectivity to determine the per-act transmission probability of an HIV+ individual during the AIDS stage.

 
{
    "AIDS_Stage_Infectivity_Multiplier": 8
}

ART_Viral_Suppression_Multiplier

float

0

1

0.08

Multiplier acting on Base_Infectivity to determine the per-act transmission probability of a virally suppressed HIV+ individual.

 
{
    "ART_Viral_Suppression_Multiplier": 0.3
}

Birth_Rate_Time_Dependence

enum

NA

NA

NONE

A scale factor for BirthRate that allows it to be altered by time or season. Enable_Birth must be set to true (1). Possible values are:

NONE

Birth rate does not vary by time.

SINUSOIDAL_FUNCTION_OF_TIME

Allows birth rate to be time-dependent, following a sinusoidal shape defined by \(1 + \sin \text{Birth\_Rate\_Sinusoidal\_Forcing\_Amplitude} \times \sin(2 \pi \times (\text{day} - \sin \text{Birth\_Rate\_Sinusoidal\_Forcing\_Phase})/365)\). Set Birth_Rate_Sinusoidal_Forcing_Amplitude and Birth_Rate_Sinusoidal_Forcing_Phase.

ANNUAL_BOXCAR_FUNCTION

Allows birth rate to follow a boxcar function. The scale factor will be equal to 1 except for a single interval in which it is equal to a given constant equal to 1 + Birth_Rate_Boxcar_Forcing_Amplitude. Set Birth_Rate_Boxcar_Forcing_Amplitude, Birth_Rate_Boxcar_Forcing_End_Time, and Birth_Rate_Boxcar_Forcing_Start_Time.

 
{
    "Enable_Vital_Dynamics": 1,
    "Enable_Birth": 1,
    "Birth_Rate_Time_Dependence": "ANNUAL_BOXCAR_FUNCTION"
}

CD4_At_Death_LogLogistic_Scale

float

1

1000

31.63

The scale parameter of a Weibull distribution that represents the at-death CD4 cell count.

 
{
    "CD4_At_Death_LogLogistic_Scale": 2.96
}

CD4_Post_Infection_Weibull_Scale

float

1

1000

560.432

The scale parameter of a Weibull distribution that represents the post-acute-infection CD4 cell count.

 
{
    "CD4_Post_Infection_Weibull_Scale": 550
}

Coital_Dilution_Factor_2_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly two current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_2_Partners": 0.5
}

Coital_Dilution_Factor_3_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly three current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_3_Partners": 0.33
}

Coital_Dilution_Factor_4_Plus_Partners

float

1.19E-0

1

1

The multiplicative reduction in the coital act rate for all relationship types when an individual has exactly three current partners. Represents coital dilution.

 
{
    "Coital_Dilution_Factor_4_Partners": 0.45
}

Condom_Transmission_Blocking_Probability

float

0

1

0.9

The per-act multiplier of the transmission probability when a condom is used.

 
{
    "Condom_Transmission_Blocking_Probability": 0.99
}

Heterogeneous_Infectiousness_LogNormal_Scale

float

0

10

0

Scale parameter of a log normal distribution that governs an infectiousness multiplier. The multiplier represents heterogeneity in infectivity and adjusts Base_Infectivity.

 
{
    "Heterogeneous_Infectiousness_LogNormal_Scale": 1
}

HIV_Adult_Survival_Shape_Parameter

float

0.001

1000

2

This parameter determines the shape of the Weibull distribution used to determine age-dependent survival time for individuals infected with HIV.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

Infectivity_Exponential_Baseline

float

0

1

0

The scale factor applied to Base_Infectivity at the beginning of a simulation, before the infectivity begins to grow exponentially. Infectivity_Scale_Type must be set to EXPONENTIAL_FUNCTION_OF_TIME.

 
{
    "Infectivity_Exponential_Baseline": 0.1,
    "Infectivity_Exponential_Delay": 90,
    "Infectivity_Exponential_Rate": 45,
    "Infectivity_Scale_Type": "EXPONENTIAL_FUNCTION_OF_TIME"
}

Male_To_Female_Relative_Infectivity_Multipliers

array of floats

NA

NA

1

An array of scale factors governing the susceptibility of females relative to males, by age. Used with Male_To_Female_Relative_Infectivity_Ages. Scaling is linearly interpolated between ages. The first value is used for individuals younger than the first age in Male_To_Female_Relative_Infectivity_Ages and the last value is used for individuals older than the last age.

 
{
    "Male_To_Female_Relative_Infectivity_Multipliers": [
        5,
        1,
        0.5
    ]
}

Maternal_Transmission_ART_Multiplier

float

0

1

0.1

The maternal transmission multiplier for on-ART mothers.

 
{
    "Maternal_Transmission_ART_Multiplier": 0.03
}

Population_Scale_Type

enum

NA

NA

USE_INPUT_FILE

The method to use for scaling the initial population specified in the demographics input file. Possible values are:

USE_INPUT_FILE

Turns off population scaling and uses InitialPopulation in the demographics file (see NodeAttributes parameters).

FIXED_SCALING

Enables Base_Population_Scale_Factor.

 
{
    "Population_Scale_Type": "FIXED_SCALING"
}

Post_Infection_Acquisition_Multiplier

float

0

1

0

The multiplicative reduction in the probability of reacquiring disease. At the time of recovery, the immunity against acquisition is multiplied by Acquisition_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Acquisition_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immune_Decay": 1,
    "Post_Infection_Acquisition_Multiplier": 0.9
}

Post_Infection_Mortality_Multiplier

float

0

1

0

The multiplicative reduction in the probability of dying from infection after getting reinfected. At the time of recovery, the immunity against mortality is multiplied by Mortality_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Mortality_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immune_Decay": 1,
    "Post_Infection_Mortality_Multiplier": 0.5
}

Post_Infection_Transmission_Multiplier

float

0

1

0

The multiplicative reduction in the probability of transmitting infection after getting reinfected. At the time of recovery, the immunity against transmission is multiplied by Transmission_Blocking_Immunity_Decay_Rate x (1 - Post_Infection_Transmission_Multiplier). Enable_Immunity must be set to 1 (true).

 
{
    "Enable_Immunity": 1,
    "Enable_Immunity_Decay": 1,
    "Post_Infection_Transmission_Multiplier": 0.9
}

STI_Coinfection_Acquisition_Multiplier

float

0

100

10

The per-act HIV acquisition probability multiplier for individuals with the STI coinfection flag.

 
{
    "STI_Coinfection_Transmission_Multiplier": 13.4,
    "STI_Coinfection_Acquisition_Multiplier": 10
}

STI_Coinfection_Transmission_Multiplier

float

0

100

10

The per-act HIV transmission probability multiplier for individuals with the STI coinfection flag.

 
{
    "STI_Coinfection_Transmission_Multiplier": 13.4,
    "STI_Coinfection_Acquisition_Multiplier": 10
}

x_Air_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by air, as provided by the migration file. Enable_Air_Migration must be set to 1.

 
{
    "Scale_Factor_Air_Migration": 1
}

x_Base_Population

float

0

3.40E+38

1

Scale factor for InitialPopulation in the demographics file (see NodeAttributes parameters). If Population_Scale_Type is set to FIXED_SCALING, the initial simulation population is uniformly scaled over the entire area to adjust for historical or future population density.

 
{
    "x_Base_Population": 0.0001
}

x_Birth

float

0

3.40E+38

1

Scale factor for birth rate, as provided by the demographics file (see NodeAttributes parameters). Enable_Birth must be set to 1.

 
{
    "x_Birth": 1
}

x_Family_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by families, as provided by the migration file. Enable_Family_Migration must be set to true (1).

 
{
    "x_Family_Migration": 1
}

x_Local_Migration

float

0

3.40E+38

1

Scale factor for rate of migration by foot travel, as provided by the migration file. Enable_Local_Migration must be set to 1.

 
{
    "x_Local_Migration": 1
}

x_Other_Mortality

float

0

3.40E+38

1

Scale factor for mortality from causes other than the disease being simulated. Base mortality is provided by the demographics file (see Complex distributions parameters). Enable_Natural_Mortality must be set to 1.

 
{
    "x_Other_Mortality": 1
}

x_Regional_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by road vehicle, as provided by the migration file. Enable_Regional_Migration must be set to 1.

 
{
    "x_Regional_Migration": 1
}

x_Sea_Migration

float

0

3.40E+38

1

Scale factor for the rate of migration by sea, as provided by the migration file. Enable_Sea_Migration must be set to 1.

 
{
    "x_Sea_Migration": 1
}
Simulation setup

These parameters determine the basic setup of a simulation including the type of simulation you are running, such as “GENERIC_SIM” or “MALARIA_SIM”, the simulation duration, and the time step duration.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Year

float

1900

2200

2015

The absolute time in years when the simulation begins. This can be combined with CampaignEventByYear to trigger campaign events (Start_Year for events must be after Base_Year).

 
{
    "Base_Year": 1960
}

Config_Name

string

NA

NA

UNINITIALIZED STRING

The optional, user-supplied title naming a configuration file.

 
{
    "Config_Name": "My_First_Config"
}

Custom_Coordinator_Events

array of strings

NA

NA

NA

The list of valid, user-defined events for Event Coordinators that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note: This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Coordinator_Events": [
        "Coordinator_Event_1",
        "Coordinator_Event_2",
        "Coordinator_Event_3"
    ]
}

Custom_Individual_Events

array of strings

NA

NA

NA

The list of valid, user-defined events that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note

This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Individual_Events": [
        "Individual_Event_1",
        "Individual_Event_2",
        "Individual_Event_3"
    ]
}

Custom_Node_Events

array of strings

NA

NA

NA

The list of valid, user-defined events for nodes that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

Note

This configuration parameter is currently in beta release and has not yet been fully tested.

 
{
    "Custom_Node_Events": [
        "Node_Event_1",
        "Node_Event_2",
        "Node_Event_3"
    ]
}

Enable_Interventions

boolean

0

1

0

Controls whether or not campaign interventions will be used in the simulation. Set Campaign_Filename to the path of the file that contains the campaign interventions.

 
{
    "Enable_Interventions": 1,
    "Campaign_Filename": "campaign.json"
}

Enable_Random_Generator_From_Serialized_Population

boolean

0

1

0

Determines if the random number generator(s) should be extracted from a serialized population file. Enabling this will start a simulation from this file with the exact same random number stream and location in that stream as when the file was serialized.

 
{
    "Run_Number": 12,
    "Random_Number_Generator_Type": "USE_AES_COUNTER",
    "Random_Number_Generator_Policy": "ONE_PER_NODE",
    "Enable_Random_Generator_From_Serialized_Population": 1
}

Enable_Skipping

boolean

0

1

0

Controls whether or not the simulation uses an optimization that can increase performance by up to 50% in some cases by probabilistically exposing individuals rather than exposing every single person. Useful in low-prevalence, high-population scenarios.

 
{
    "Enable_Skipping": 0
}

Enable_Termination_On_Zero_Total_Infectivity

boolean

0

1

0

Controls whether or not the simulation should be ended when total infectivity falls to zero. Supported only in single-node simulations.

 
{
    "Enable_Termination_On_Zero_Total_Infectivity": 1,
    "Minimum_End_Time": 3650
}

Listed_Events

array of strings

NA

NA

[]

The list of valid, user-defined events that will be included in the campaign. Any event used in the campaign must either be one of the built-in events or in this list.

 
{
    "Listed_Events": [
        "Vaccinated",
        "VaccineExpired"
    ]
}

Memory_Usage_Halting_Threshold_Working_Set_MB

integer

0

1.00E+06

8000

The maximum size (in MB) of working set memory before the system throws an exception and halts.

 
{
    "Memory_Usage_Halting_Threshold_Working_Set_MB": 4000
}

Memory_Usage_Warning_Threshold_Working_Set_MB

integer

0

1.00E+06

7000

The maximum size (in MB) of working set memory before memory usage statistics are written to the log regardless of log level.

 
{
    "Memory_Usage_Warning_Threshold_Working_Set_MB": 3500
}

Node_Grid_Size

float

0.00416

90

0.004167

The spatial resolution indicating the node grid size for a simulation in degrees.

 
{
    "Node_Grid_Size": 0.042
}

Random_Number_Generator_Policy

enum

NA

NA

ONE_PER_CORE

The policy that determines if random numbers are generated for objects in a simulation on a per-core or per-node basis. The following values are available:

ONE_PER_CORE

A random number generator (RNG) is created for each computing core running a simulation. When running a simulation on a single core, there will be only one RNG. If running the single simulation on multiple cores, each core will have its own RNG. The RNGs on the different cores start out such that they will not generate the same stream of random numbers. Prior to EMOD 2.19, all simulations used this policy.

ONE_PER_NODE

An RNG is created for each geographic node in the simulation. The advantages of this policy are that 1) an event that causes a random number to be drawn in one node does not cause things to change in another node and 2) changing a simulation from single core to multi-core will not change the results. The RNGs on the different nodesstart out such that they will not generate the same stream of random numbers.

 
{
    "Run_Number": 15,
    "Random_Number_Generator_Type": "USE_AES_COUNTER",
    "Random_Number_Generator_Policy": "ONE_PER_NODE"
}

Random_Number_Generator_Type

enum

NA

NA

USE_PSEUDO_DES

The type of random number generator to use for objects in a simulation. Must set the RNG seed in Run_Number. The following values are available:

USE_PSEUDO_DES

Based on Numerical Recipes in C. The Art of Scientific Computing, 2nd ed. Press, William H. et. al, 1992. Prior to EMOD 2.19, this was the only generator available.

USE_LINEAR_CONGRUENTIAL

Based on The Structure of Linear Congruential Sequences, Marsaglia, George, 1972.

USE_AES_COUNTER

Based on AES in CTR Mode encryption as implemented in Intel (R) Advanced Encryption Standard (AES) New Instruction Set.

 
{
    "Run_Number": 15,
    "Random_Number_Generator_Type": "USE_LINEAR_CONGRUENTIAL",
    "Random_Number_Generator_Policy": "ONE_PER_NODE",
    "Enable_Random_Generator_From_Serialized_Population": 1
}

Run_Number

integer

0

65535

1

Sets the random number seed used with Random_Number_Generator_Type and Random_Number_Generator_Policy to assign random numbers to objects in a simulation. This value must be different for each simulation run to ensure model stochasticity.

 
{
    "Run_Number": 15,
    "Random_Number_Generator_Type": "USE_PSEUDO_DES",
    "Random_Number_Generator_Policy": "ONE_PER_NODE",
    "Enable_Random_Generator_From_Serialized_Population": 1
}

Serialization_Times

array of floats

0

The list of times at which to save the serialized state to file. 0 indicates the initial state before simulation, n indicates the time to serialize in terms of start time and step size, and will be rounded up to the nearest time step. The serialized population files can then be loaded at the beginning of a simulation using Serialized_Population_Filenames and Serialized_Population_Path.

 
{
    "Serialization_Type": "TIME",
    "Serialization_Times": [
        40.5,
        81
    ]
}

Serialization_Time_Steps

array of integers

0

2.15E+09

The list of time steps after which to save the serialized state to file. 0 (zero) indicates the initial state before simulation, n indicates after the nth time step. Serialization_Type must be set to TIMESTEP. The serialized population files can then be loaded at the beginning of a simulation using Serialized_Population_Filenames and Serialized_Population_Path.

 
{
    "Serialization_Type": "TIMESTEP",
    "Serialization_Time_Steps": [
        0,
        10
    ]
}

Serialization_Type

enum

NA

NA

NONE

The type of serialization to perform. Serialization saves the population state at particular times so you can start from that state in other simulations. Accepted values are:

NONE

No serialization.

TIME

Use the definition from Serialization_Times.

TIMESTEP

Use the definition from Serialization_Timestep.

 
{
    "Serialization_Times": [
        365,
        3650
    ],
    "Serialization_Type": "TIMSTEP"
}

j

{}

Serialized_Population_Filenames

array of strings

NA

NA

NA

An array of filenames with serialized population data. The number of filenames must match the number of cores used for the simulation. The files must be in .dtk format. Serialized population files are created using Serialization_Time_Steps.

 
{
    "Serialized_Population_Filenames": [
        "state-00010.dtk"
    ]
}

Serialized_Population_Path

string

NA

NA

.

The root path for the serialized population files. Serialized population files are created using Serialization_Time_Steps.

 
{
    "Serialized_Population_Path": "../00_Generic_Version_1_save/output"
}

Simulation_Duration

float

0

1000000

1

The elapsed time (in days) from the start to the end of a simulation.

 
{
    "Simulation_Duration": 7300
}

Simulation_Timestep

float

0

1000000

1

The duration of a simulation time step, in days.

 
{
    "Simulation_Timestep": 1
}

Simulation_Type

enum

NA

NA

GENERIC_SIM

The type of disease being simulated. Possible IDM-supported values are:

  • GENERIC_SIM

  • VECTOR_SIM

  • MALARIA_SIM

  • TBHIV_SIM

  • STI_SIM

  • HIV_SIM

  • ENVIRONMENTAL_SIM

  • TYPHOID_SIM

 
{
    "Simulation_Type": "STI_SIM"
}

Start_Time

float

0

1000000

1

The time, in days, when the simulation begins. This time is used to identify the starting values of the temporal input data, such as specifying which day’s climate values should be used for the first day of the simulation.

Note

The Start_Day of campaign events is in absolute time, so time relative to the beginning of the simulation depends on this parameter.

 
{
    "Start_Time": 365
}
Symptoms and diagnosis

The following parameters determine the characteristics of HIV diagnosis and HIV/AIDS symptoms, such as CD4 counts at various times in the progression of the disease.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

CD4_At_Death_LogLogistic_Scale

float

1

1000

31.63

The scale parameter of a Weibull distribution that represents the at-death CD4 cell count.

 
{
    "CD4_At_Death_LogLogistic_Scale": 2.96
}

CD4_Post_Infection_Weibull_Heterogeneity

float

0

100

0.275642

The inverse shape parameter of a Weibull distribution that represents the post-acute-infection CD4 cell count.

 
{
    "CD4_Post_Infection_Weibull_Heterogeneity": 0
}

CD4_Post_Infection_Weibull_Scale

float

1

1000

560.432

The scale parameter of a Weibull distribution that represents the post-acute-infection CD4 cell count.

 
{
    "CD4_Post_Infection_Weibull_Scale": 550
}

Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity

float

0.1

10

1

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the heterogeneity (inverse shape) of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity": 0.5
}

Days_Between_Symptomatic_And_Death_Weibull_Scale

float

1

3650

183

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the scale of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Scale": 618.3
}
Weibull distributions

The following parameters use a Weibull distribution.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

CD4_At_Death_LogLogistic_Heterogeneity

float

0

100

0

The inverse shape parameter of a Weibull distribution that represents the at-death CD4 cell count.

 
{
    "CD4_At_Death_LogLogistic_Heterogeneity": 0.7
}

CD4_At_Death_LogLogistic_Scale

float

1

1000

31.63

The scale parameter of a Weibull distribution that represents the at-death CD4 cell count.

 
{
    "CD4_At_Death_LogLogistic_Scale": 2.96
}

CD4_Post_Infection_Weibull_Heterogeneity

float

0

100

0.275642

The inverse shape parameter of a Weibull distribution that represents the post-acute-infection CD4 cell count.

 
{
    "CD4_Post_Infection_Weibull_Heterogeneity": 0
}

CD4_Post_Infection_Weibull_Scale

float

1

1000

560.432

The scale parameter of a Weibull distribution that represents the post-acute-infection CD4 cell count.

 
{
    "CD4_Post_Infection_Weibull_Scale": 550
}

Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity

float

0.1

10

1

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the heterogeneity (inverse shape) of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Heterogeneity": 0.5
}

Days_Between_Symptomatic_And_Death_Weibull_Scale

float

1

3650

183

The time between the onset of AIDS symptoms and death is sampled from a Weibull distribution; this parameter governs the scale of the Weibull.

 
{
    "Days_Between_Symptomatic_And_Death_Weibull_Scale": 618.3
}

HIV_Adult_Survival_Scale_Parameter_Intercept

float

0.001

1000

21.182

This parameter determines the intercept of the scale parameter, ?, for the Weibull distribution used to determine HIV survival time.

Survival time with untreated HIV infection depends on the age of the individual at the time of infection, and is drawn from a Weibull distribution with shape parameter (see HIV_Adult_Survival_Shape_Parameter) and scale parameter, ?. The scale parameter is allowed to vary linearly with age as follows:

\(\lambda\) = HIV_Adult_Survival_Scale_Parameter_Intercept + HIV_Adult_Survival_Scale_ Parameter_Slope * Age (in years).

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Adult_Survival_Scale_Parameter_Slope

float

-1000

1000

-0.2717

This parameter determines the slope of the scale parameter, ?, for the Weibull distribution used to determine HIV survival time.

Survival time with untreated HIV infection depends on the age of the individual at the time of infection, and is drawn from a Weibull distribution with shape parameter (see HIV_Adult_Survival_Shape_Parameter) and scale parameter, ?. The scale parameter is allowed to vary linearly with age as follows:

\(\lambda\) = HIV_Adult_Survival_Scale_Parameter_Intercept + HIV_Adult_Survival_Scale_ Parameter_Slope * Age (in years).

Because survival time with HIV becomes shorter with increasing age, HIV_Adult_Survival_Scale_ Parameter_Slope should be set to a negative number.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Adult_Survival_Shape_Parameter

float

0.001

1000

2

This parameter determines the shape of the Weibull distribution used to determine age-dependent survival time for individuals infected with HIV.

 
{
    "HIV_Adult_Survival_Scale_Parameter_Intercept": 21.182,
    "HIV_Adult_Survival_Scale_Parameter_Slope": -0.2717,
    "HIV_Adult_Survival_Shape_Parameter": 2.0,
    "HIV_Age_Max_for_Adult_Age_Dependent_Survival": 50.0
}

HIV_Child_Survival_Slow_Progressor_Scale

float

0.001

1000

16

The Weibull scale parameter describing the distribution of HIV survival for children who are slower progressors.

 
{
    "HIV_Child_Survival_Slow_Progressor_Scale": 16.0,
    "HIV_Child_Survival_Slow_Progressor_Shape": 2.7
}

HIV_Child_Survival_Slow_Progressor_Shape

float

0.001

1000

2.7

The Weibull shape parameter describing the distribution of HIV survival for children who are slower progressors.

 
{
    "HIV_Child_Survival_Slow_Progressor_Scale": 16.0,
    "HIV_Child_Survival_Slow_Progressor_Shape": 2.7
}

Sexual_Debut_Age_Female_Weibull_Heterogeneity

float

0

50

20

The inverse shape of the Weibull distribution for female debut age.

 
{
    "Sexual_Debut_Age_Female_Weibull_Heterogeneity": 0.05
}

Sexual_Debut_Age_Female_Weibull_Scale

float

0

50

16

The scale term of the Weibull distribution for female debut age.

 
{
    "Sexual_Debut_Age_Female_Weibull_Scale": 15.919654846191
}

Sexual_Debut_Age_Male_Weibull_Heterogeneity

float

0

50

20

The inverse shape of the Weibull distribution for male debut age.

 
{
    "Sexual_Debut_Age_Male_Weibull_Heterogeneity": 0.05
}

Sexual_Debut_Age_Male_Weibull_Scale

float

0

50

16

The scale term of the Weibull distribution for male debut age.

 
{
    "Sexual_Debut_Age_Male_Weibull_Scale": 16.946729660034
}

Sexual_Debut_Age_Min

float

0

3.40E+38

13

The minimum age at which individuals become eligible to form sexual relationships.

 
{
    "Sexual_Debut_Age_Min": 13
}
Campaign parameters

The parameters described in this reference section can be added to the JSON (JavaScript Object Notation) formatted campaign file to determine the interventions that are used to control the spread of disease and where, when, how, and to whom the interventions are distributed. Additionally, the campaign file specifies the details of the outbreak of the disease itself. For more conceptual background on how to create a campaign file, see Creating campaigns.

In the configuration file, you must set the Enable_Interventions parameter to 1 and set the Campaign_Filename parameter to the name of the campaign file for the interventions to take place. The campaign file must be in the same directory as the configuration file.

The campaign file is hierarchically organized into logical groups of parameters that can have arbitrary levels of nesting. It contains an Events array of campaign events, each of which contains a JSON object describing the event coordinator, which in turn contains a nested JSON object describing the intervention. At the same level as the Events array is the boolean Use_Defaults to indicate whether or not to use the default values for required parameters that are not included in the file. It is common to include JSON keys for campaign name, event name, or intervention name; these are informational only and not used by EMOD.

The skeletal JSON example below illustrates the basic file structure (this does not include all required parameters for each object). Note that the nested JSON elements have been organized to best illustrate their hierarchy, but that many files in the EMOD GitHub repository list the parameters and nested objects differently.

{
    "Campaign_Name": "Campaign example",
    "Use_Defaults": 1,
    "Events": [{
        "Event_Name": "The first event",
        "class": "CampaignEvent",
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "Intervention_Name": "The vaccine",
                "class": "SimpleVaccine"
            }
        }
    }, {
        "Event_Name": "The second event",
        "class": "CampaignEvent",
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "Intervention_Name": "The disease outbreak",
                "class": "OutbreakIndividual"
            }
        }
    }]
}

The topics below contain only parameters available when using the HIV simulation type. The

Events and event coordinators

Campaign events determine when and where an intervention is distributed during a campaign. “When” can be the number of days after the beginning of the simulation or at a point during a particular calendar year. “Where” is the geographic node or nodes in which the event takes place.

Event coordinators are nested within the campaign event JSON object and determine who receives the intervention. “Who” is determined by filtering on age, gender, or on the individual properties configured in the demographics files, such as risk group or sociodemographic category. See Individual and node properties.

BroadcastCoordinatorEvent

Note

This campaign class and associated parameters are currently in beta release and have not yet been fully tested.

The BroadcastCoordinatorEvent coordinator class broadcasts the event you specify. This can be used with the campaign class, SurveillanceEventCoordinator, that can monitor and listen for events received from BroadcastCoordinatorEvent and then perform an action based on the broadcasted event. You can also use this for the reporting of the broadcasted events by setting the configuraton parameters, Report_Node_Event_Recorder and Report_Surveillance_Event_Recorder, which listen to events to be recorded. You must use this coordinator class with listeners that are operating on the same core. For more information, see Simulation core components.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The name of the event to be broadcast. This event must be set in the Custom_Coordinator_Events configuration parameter. This cannot be assigned an empty string for the event.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_1",
        "Cost_To_Consumer": 10,
        "Broadcast_Event": "Coordinator_Event_1"
    }
}

Coordinator_Name

string

NA

NA

NA

The unique identifying coordinator name, which is useful with the output report, ReportCoordinatorEventRecorder.csv.

 
{
    "class": "CampaignEvent",
    "Start_Day": 25,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordinator_3",
        "Cost_To_Consumer": 30,
        "Broadcast_Event": "Coordinator_Event_3"
    }
}

Cost_To_Consumer

float

0

3.40282e+38

0

The unit cost of broadcasting the event.

 
{
    "class": "CampaignEvent",
    "Start_Day": 15,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_2",
        "Cost_To_Consumer": 20,
        "Broadcast_Event": "Coordinator_Event_2"
    }
}

{
    "Events": [

        {
            "comment": "Broadcast Event to start Surveillance",
            "class": "CampaignEvent",
            "Start_Day": 2,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "BroadcastCoordinatorEvent",
                "Coordinator_Name" : "Coordnator_1",
                "Cost_To_Consumer" : 10,
                "Broadcast_Event" : "Start_ACF"
            }
        },
        {
            "comment": "Triggered by Broadcast_Event, stops itself by broadcasting Start_SIA_X Event",
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "SurveillanceEventCoordinator",
                "Coordinator_Name" : "ACF_Counter",
                "Start_Trigger_Condition_List" : [ "Start_ACF" ],
                "Stop_Trigger_Condition_List" : [ 
                    "Start_SIA_2", 
                    "Start_SIA_4"
                ],
                "Duration" : -1,
                "Incidence_Counter" : {
                    "Counter_Type" : "PERIODIC",
                    "Counter_Period" : 365,
                    "Counter_Event_Type" : "INDIVIDUAL",
                    "Trigger_Condition_List" : ["HappyBirthday"],
                    "Node_Property_Restrictions" : [],
                    "Property_Restrictions_Within_Node" : [],
                    "Target_Demographic": "Everyone",
                    "Demographic_Coverage" : 1.0
                },
                "Responder" : {
                    "Threshold_Type" : "COUNT",
                    "Action_List" :
                    [
                        {
                            "Threshold" : 8,
                            "Event_Type" : "COORDINATOR",
                            "Event_To_Broadcast" : "Ind_Start_SIA_2"
                        },
                        {
                            "Threshold" : 5,
                            "Event_Type" : "COORDINATOR",
                            "Event_To_Broadcast" : "Ind_Start_SIA_4"
                        }
                    ]
                }
            }            
        }
    ],
    "Use_Defaults": 1
}
CalendarEventCoordinator

The CalendarEventCoordinator coordinator class distributes individual-level interventions at a specified time and coverage. See the following JSON example and table, which shows all available parameters for this event coordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Distribution_Coverages

array of floats

0

1

0

A vector of floats for the fraction of individuals that will receive this intervention in a CalendarEventCoordinator.

 
{
    "Distribution_Times": [
        100,
        200,
        400,
        800,
        1200
    ],
    "Distribution_Coverages": [
        0.01,
        0.05,
        0.1,
        0.2,
        1.0
    ]
}

Distribution_Times

array of integers

1

2147480000.0

0

A vector of integers for simulation times at which distribution of events occurs in a CalendarEventCoordinator. These times must be in ascending order.

 
{
    "Distribution_Times": [
        100,
        200,
        400,
        800,
        1200
    ],
    "Distribution_Coverages": [
        0.01,
        0.05,
        0.1,
        0.2,
        1.0
    ]
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Incubation_Period_Override": 1,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Timesteps_Between_Repetitions": 50
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Events": [{
        "class": "CampaignEvent",
        "Event_Name": "High-risk vaccination",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "CalendarEventCoordinator",
            "Demographic_Coverage": 1,
            "Property_Restrictions": [
                "Risk:High"
            ],
            "Number_Repetitions": 1,
            "Timesteps_Between_Repetitions": 0,
            "Target_Demographic": "Everyone",
            "Target_Residents_Only": 1,
            "Distribution_Times": [100, 200, 400, 800, 1200],
            "Distribution_Coverages": [0.01, 0.05, 0.1, 0.2, 1.0],
            "Intervention_Config": {
                "Cost_To_Consumer": 0,
                "Vaccine_Take": 1,
                "Vaccine_Type": "AcquisitionBlocking",
                "class": "SimpleVaccine",
                "Waning_Config": {
                    "Initial_Effect": 1,
                    "Box_Duration": 1825,
                    "class": "WaningEffectBox"
                }
            }
        }
    }]
}
CampaignEvent

The CampaignEvent event class determines when to distribute the intervention based on the first day of the simulation. See the following JSON example and table, which shows all available parameters for this campaign event.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Event_Coordinator_Config

JSON object

NA

NA

NA

An object that specifies how the event is handled by the simulation. It specifies which Event Coordinator class will handle the event, and then configures the coordinator. This description starts with specifying class, and then the other fields depend on the class.

 
{
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1.0
    }
}

Event_Name

string

NA

NA

NA

The optional name used to refer to this event as a means to differentiate it from others that use the same class.

 
{
    "Events": [
        {
            "Event_Name": "Outbreak",
            "class": "CampaignEvent",
            "Nodeset_Config": "NodeSetAll"
        }
    ]
}

Nodeset_Config

JSON object

NA

NA

NA

An object that specifies in which nodes the interventions will be distributed. Set to one of the Nodeset_Config classes.

 
{
    "Nodeset_Config": {
        "class": "NodeSetAll"
    }
}

Start_Day

float

0

3.40282e+38

1

The day of the simulation to activate the event’s event coordinator. Depending on the event coordinator and intervention, this may indicate when to distribute an intervention or when to begin listening for a trigger.

 
{
    "Start_Day": 0,
    "End_Day": 100
}

{
    "Events": [{
        "class": "CampaignEvent",
        "Event_Name": "Individual outbreak",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "class": "OutbreakIndividual"
            }
        }
    }]
}
Nodeset_Config classes

The following classes determine in which nodes the event will occur.

NodeSetAll

The event will occur in all nodes in the simulation. This class has no associated parameters. For example,

{
    "Nodeset_Config": {
        "class": "NodeSetAll"
    }
}
NodeSetNodeList

The event will occur in the nodes listed by Node ID.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Node_List

array of integers

NA

NA

NA

A comma-separated list of node IDs in which this event will occur.

 
{
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1,
            5,
            27
        ]
    }
}
NodeSetPolygon

The event will occur in the nodes that fall within a given polygon.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Polygon_Format

enum

NA

NA

SHAPE

The type of polygon to create. Currently, SHAPE is the only supported value.

 
{
    "Nodeset_Config": {
        "class": "NodeSetPolygon",
        "Polygon_Format": "SHAPE",
        "Vertices": "-122.320726936496,47.6597902588541 -122.320406460197,47.6520988276782 -122.308388598985,47.6471314450438"
    }
}

Vertices

string

NA

NA

UNINTIALIZED STRING

Comma-separated list of latitude/longitude points that bound a polygon.

 
{
    "Nodeset_Config": {
        "class": "NodeSetPolygon",
        "Polygon_Format": "SHAPE",
        "Vertices": "-122.320726936496,47.6597902588541 -122.320406460197,47.6520988276782 -122.308388598985,47.6471314450438"
    }
}
CampaignEventByYear

The CampaignEventByYear event class determines when to distribute the intervention based on the calendar year. See the following JSON example and table, which shows all available parameters for this campaign event.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Event_Coordinator_Config

JSON object

NA

NA

NA

An object that specifies how the event is handled by the simulation. It specifies which Event Coordinator class will handle the event, and then configures the coordinator. This description starts with specifying class, and then the other fields depend on the class.

 
{
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1.0
    }
}

Nodeset_Config

JSON object

NA

NA

NA

An object that specifies in which nodes the interventions will be distributed. Set to one of the Nodeset_Config classes.

 
{
    "Nodeset_Config": {
        "class": "NodeSetAll"
    }
}

Start_Year

float

1900

2200

1900

The absolute year of the simulation to activate the event’s event coordinator. To have the intervention applied other than at the beginning of the year, you must enter a decimal value after the year. For example, 2010.5 would have the intervention applied halfway through the year 2010.

 
{
    "Start_Year": 1962
}

{
    "Events": [{
        "class": "CampaignEventByYear",
        "Event_Name": "Everyone initiates ART",
        "Start_Year": 2025,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1,
            "Travel_Linked": 0,
            "Intervention_Config": {
                "class": "ARTBasic"
            }
        }
    }]
}
Nodeset_Config classes

The following classes determine in which nodes the event will occur.

NodeSetAll

The event will occur in all nodes in the simulation. This class has no associated parameters. For example,

{
    "Nodeset_Config": {
        "class": "NodeSetAll"
    }
}
NodeSetNodeList

The event will occur in the nodes listed by Node ID.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Node_List

array of integers

NA

NA

NA

A comma-separated list of node IDs in which this event will occur.

 
{
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1,
            5,
            27
        ]
    }
}
NodeSetPolygon

The event will occur in the nodes that fall within a given polygon.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Polygon_Format

enum

NA

NA

SHAPE

The type of polygon to create. Currently, SHAPE is the only supported value.

 
{
    "Nodeset_Config": {
        "class": "NodeSetPolygon",
        "Polygon_Format": "SHAPE",
        "Vertices": "-122.320726936496,47.6597902588541 -122.320406460197,47.6520988276782 -122.308388598985,47.6471314450438"
    }
}

Vertices

string

NA

NA

UNINTIALIZED STRING

Comma-separated list of latitude/longitude points that bound a polygon.

 
{
    "Nodeset_Config": {
        "class": "NodeSetPolygon",
        "Polygon_Format": "SHAPE",
        "Vertices": "-122.320726936496,47.6597902588541 -122.320406460197,47.6520988276782 -122.308388598985,47.6471314450438"
    }
}
CommunityHealthWorkerEventCoordinator

The CommunityHealthWorkerEventCoordinator coordinator class is used to model a health care worker’s ability to distribute interventions to the nodes and individual in their coverage area. This coordinator distributes a limited number of interventions per day, and can create a backlog of individuals or nodes requiring the intervention. For example, individual-level interventions could be distribution of drugs and node-level interventions could be spraying houses with insecticide.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Amount_In_Shipment

integer

1

2147480000.0

2147480000.0

The number of interventions (such as vaccine doses) that a health worker or clinic receives in a shipment. Interventions can only be distributed if they are in stock; stock is updated every Days_Between_Shipments with the Amount_In_Shipment.

 
{
    "Amount_In_Shipment": 10
}

Days_Between_Shipments

float

1

3.40282e+38

3.40E+38

The number of days to wait before a clinic or health worker receives a new shipment of interventions (such as vaccine doses). Interventions can only be distributed if they are in stock; stock is updated every Days_Between_Shipments with the Amount_In_Shipment.

 
{
    "Days_Between_Shipments": 30
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Duration

float

0

3.40282e+38

3.40E+38

The number of days for an event coordinator to be active before it expires.

 
{
    "Duration": 65
}

Initial_Amount_Constant

float

0

3.40282E+38

-1

The initial amount to use for all health workers when Initial_Amount_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "CONSTANT_DISTRIBUTION",
    "Initial_Amount_Constant": 8
}

Initial_Amount_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the initial amount of interventions in stock. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Initial_Amount_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Initial_Amount_Max and Initial_Amount_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Initial_Amount_Gaussian_Mean and Initial_Amount_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Initial_Amount_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Initial_Amount_Kappa and Initial_Amount_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Initial_Amount_Log_Normal_Mu and Initial_Amount_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Initial_Amount_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Initial_Amount_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Initial_Amount_Mean_1, Initial_Amount_Mean_2, and Initial_Amount_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Exponential

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Exponential": 4.25
}

Initial_Amount_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Initial_Amount_Gaussian_Mean": 8,
    "Initial_Amount_Gaussian_Std_Dev": 1.5
}

Initial_Amount_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the initial amount of intervention in stock when Initial_Amount_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Initial_Amount_Gaussian_Mean": 8,
    "Initial_Amount_Gaussian_Std_Dev": 1.5
}

Initial_Amount_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the initial amount of intervention in stock when Initial_Amount_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "WEIBULL_DISTRIBUTION",
    "Initial_Amount_Kappa": 0.9,
    "Initial_Amount_Lambda": 1.5
}

Initial_Amount_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the initial amount of intervention in stock when Initial_Amount_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "WEIBULL_DISTRIBUTION",
    "Initial_Amount_Kappa": 0.9,
    "Initial_Amount_Lambda": 1.5
}

Initial_Amount_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the initial amount of intervention in stock when Initial_Amount_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Initial_Amount_Log_Normal_Mu": 9,
    "Initial_Amount_Log_Normal_Sigma": 2
}

Initial_Amount_Log_Normal_Sigma

float

-3.40282e+38

3.40282E+38

1

The standard deviation of the natural log of the initial amount of intervention in stock when Initial_Amount_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Initial_Amount_Log_Normal_Mu": 9,
    "Initial_Amount_Log_Normal_Sigma": 2
}

Initial_Amount_Max

float

0

3.40282E+38

-1

The maximum initial amount of intervention in stock when Initial_Amount_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "UNIFORM_DISTRIBUTION",
    "Initial_Amount_Min": 2,
    "Initial_Amount_Max": 7
}

Initial_Amount_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Initial_Amount_Min

float

0

3.40282E+38

-1

The minimum of initial amount of intervention in stock when Initial_Amount_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "UNIFORM_DISTRIBUTION",
    "Initial_Amount_Min": 2,
    "Initial_Amount_Max": 7
}

Initial_Amount_Peak_2_Value

float

0

3.40282E+38

-1

The initial amount in stock to assign to the remaining health workers when Initial_Amount_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Initial_Amount_Proportion_0": 0.25,
    "Initial_Amount_Peak_2_Value": 5
}

Initial_Amount_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the initial amount of intervention in stock when Initial_Amount_Distribution is set to the POISSON_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "POISSON_DISTRIBUTION",
    "Initial_Amount_Poisson_Mean": 5
}

Initial_Amount_Proportion_0

float

0

1

-1

The proportion of health workers to assign a value of zero stock when Initial_Amount_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Initial_Amount_Proportion_0": 0.25,
    "Initial_Amount_Peak_2_Value": 5
}

Initial_Amount_Proportion_1

float

0

1

-1

The proportion of health workers in the first exponential distribution when Initial_Amount_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Initial_Amount_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Initial_Amount_Mean_1": 4,
    "Initial_Amount_Mean_2": 12,
    "Initial_Amount_Proportion_1": 0.2
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "BroadcastEvent",
        "Broadcast_Event": "EventFromIntervention"
    }
}

Max_Distributed_Per_Day

integer

1

2147480000.0

2147480000.0

The maximum number of interventions (such as vaccine doses) that can be distributed by health workers or clinics in a given day.

 
{
    "Max_Distributed_Per_Day": 1
}

Max_Stock

integer

0

2147480000.0

2147480000.0

The maximum number of interventions (such as vaccine doses) that can be stored by a health worker or clinic. If the amount of interventions in a new shipment and current stock exceeds this value, only the number of interventions specified by this value will be stored.

 
{
    "Max_Stock": 12
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Trigger_Condition_List

array of strings

NA

NA

NA

The list of events that are of interest to the community health worker (CHW). If one of these events occurs, the individual or node is put into a queue to receive the CHW’s intervention. The CHW processes the queue when the event coordinator is updated. See Event list for possible values.

 
{
    "Trigger_Condition_List": [
        "ListenForEvent"
    ]
}

Waiting_Period

float

0

3.40282e+38

3.40E+38

The number of days a person or node can be in the queue waiting to get the intervention from the community health worker (CHW). If a person or node is in the queue, they will not be re-added to the queue if the event that would add them to the queue occurs. This allows them to maintain their priority, however they could be removed from the queue due to this waiting period.

 
{
    "Waiting_Period": 15
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
  "Events": [
    {
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
          2,
          3,
          4
        ]
      },
      "Event_Coordinator_Config": {
        "class": "CommunityHealthWorkerEventCoordinator",
        "Duration": 400,
        "Distribution_Rate": 25,
        "Waiting_Period": 10,
        "Days_Between_Shipments": 25,
        "Amount_In_Shipment": 250,
        "Max_Stock": 1000,
        "Initial_Amount_Distribution": "CONSTANT_DISTRIBUTION",
        "Initial_Amount_Constant": 500,
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 1.0,
        "Property_Restrictions": [],
        "Target_Residents_Only": 0,
        "Trigger_Condition_List": [
          "NewInfectionEvent"
        ],
        "Intervention_Config": {
          "class": "SimpleVaccine",
          "Cost_To_Consumer": 10.0,
          "Vaccine_Take": 1,
          "Vaccine_Type": "AcquisitionBlocking",
          "Waning_Config": {
            "class": "WaningEffectBox",
            "Initial_Effect": 1,
            "Box_Duration": 200
          }
        }
      }
    }
  ]
}
CoverageByNodeEventCoordinator

The CoverageByNodeEventCoordinator coordinator class distributes individual-level interventions and is similar to the StandardInterventionDistributionEventCoordinator, but adds the ability to specify different demographic coverages by node. If no coverage has been specified for a particular node ID, the coverage will be zero. See the following JSON example and table, which shows all available parameters for this event coordinator.

Note

This can only be used with individual-level interventions, but EMOD will not produce an error if you attempt to use it with an node-level intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Coverage_By_Node

array of arrays

NA

NA

NA

An array of (nodeID, coverage) pairs configuring the demographic coverage of interventions by node for the targeted populations. The coverage value must be a float between 0 and 1.

 
{
    "Event_Coordinator_Config": {
        "Coverage_By_Node": [
            [
                1,
                0.6
            ],
            [
                2,
                0.9
            ],
            [
                3,
                0.1
            ]
        ]
    }
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Incubation_Period_Override": 1,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "Outbreak",
            "Num_Cases": 1
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 50,
        "class": "StandardInterventionDistributionEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Timesteps_Between_Repetitions": 50
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 0,
        "Nodeset_Config": {
            "Node_List": [
                1,
                2,
                3
            ],
            "class": "NodeSetNodeList"
        },
        "Event_Coordinator_Config": {
            "class": "CoverageByNodeEventCoordinator",
            "Target_Demographic": "Everyone",
            "Coverage_By_Node": [
                [1, 0.6],
                [2, 0.9],
                [3, 0.1]
            ],
            "Intervention_Config": {
                "Cost_To_Consumer": 10.0,
                "Reduced_Transmit": 0,
                "Vaccine_Take": 1,
                "Vaccine_Type": "AcquisitionBlocking",
                "Waning_Config": {
                    "Box_Duration": 3650,
                    "Initial_Effect": 1,
                    "class": "WaningEffectBox"
                },
                "class": "SimpleVaccine"
            }
        }
    }]
}
DelayEventCoordinator

Note

This campaign class and associated parameters are currently in beta release and have not yet been fully tested.

The DelayEventCoordinator coordinator class insert delays into coordinator event chains. This campaign event is typically used with BroadcastCoordinatorEvent to broadcast events after the delays.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Coordinator_Name

string

NA

NA

DelayEventCoordinator

The unique identifying coordinator name, which is useful with the output report, ReportCoordinatorEventRecorder.csv.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Delay_Complete_Event

string

NA

NA

NA

The delay completion event to be included in the ReportCoordinatorEventRecorder.csv output report, upon completion of the delay period.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Distribution": "GAUSSIAN_DURATION",
        "Delay_Period_Mean": 25,
        "Delay_Period_Std_Dev": 5,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Delay_Period_Constant

float

0

3.40282E+38

-1

The delay period to use for all interventions, in days, when Delay_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Delay_Period_Constant": 8
}

Delay_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Delay_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Delay_Period_Max and Delay_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Delay_Period_Gaussian_Mean and Delay_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Delay_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Delay_Period_Kappa and Delay_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Delay_Period_Log_Normal_Mu and Delay_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Delay_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Delay_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Delay_Period_Mean_1, Delay_Period_Mean_2, and Delay_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Exponential

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Exponential": 4.25
}

Delay_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Max

float

0

3.40282E+38

-1

The maximum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Min

float

0

3.40282E+38

-1

The minimum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Peak_2_Value

float

0

3.40282E+38

-1

The delay period value, in days, to assign to the remaining interventions when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "POISSON_DISTRIBUTION",
    "Delay_Period_Poisson_Mean": 5
}

Delay_Period_Proportion_0

float

0

1

-1

The proportion of interventions to assign a value of zero delay when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Proportion_1

float

0

1

-1

The proportion of interventions in the first exponential distribution when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Duration

float

-1

3.40282e+38

-1

The number of days from when the delay event coordinator was created by the campaign event. Once the number of days has passed, the delay event coordinator will unregister for events and expire. The default value of ‘-1’ = never expire.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent"
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The start trigger event condition list contains events defined in the Custom_Coordinator_Events config parameter that will trigger to start a new delay. If the delay event coordinator has already been triggered and is currently waiting for the duration of a delay, it will then ignore a new delay event. The list cannot be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The stop trigger event condition list contains events defined in the Custom_Coordinator_Events config parameter that will trigger to stop a delay period, but does not stop the delay event coordinator. The event is not broadcast.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Distribution": "FIXED_DURATION",
        "Delay_Period_Fixed": 25,
        "Duration": 100,
        "Start_Trigger_Condition_List": [
            "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "DelayEventCoordinator"
    },
    "Event_Name": "Delay",
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "Target_Demographic": "Everyone",
    "class": "CampaignEvent",
    "comment": "Delay"
}

{
  "Events": [
    {
      "comment": "Trigger to start Delay",
      "class": "CampaignEvent",
      "Start_Day": 2,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_1",
        "Cost_To_Consumer": 10,
        "Broadcast_Event": "Coordinator_Event_1"
      }
    },
    {
      "comment": "restart Delay",
      "class": "CampaignEvent",
      "Start_Day": 10,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "BroadcastCoordinatorEvent",
        "Coordinator_Name": "Coordnator_1",
        "Cost_To_Consumer": 10,
        "Broadcast_Event": "Coordinator_Event_1"
      }
    },
    {
      "comment": "Delay",
      "Event_Coordinator_Config": {
        "class": "DelayEventCoordinator",
        "Coordinator_Name": "DelayEventCoordinator_10",
        "Start_Trigger_Condition_List": [
          "Coordinator_Event_1"
        ],
        "Stop_Trigger_Condition_List": [],
        "Duration": 100,
        "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
        "Delay_Complete_Event": "Completion_Delayed_Coordinator_Event_1",
        "Delay_Period_Constant": 25
      },
      "Event_Name": "Delay",
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 1,
      "Target_Demographic": "Everyone",
      "class": "CampaignEvent"
    }
  ],
  "Use_Defaults": 1
}
IncidenceEventCoordinator

The IncidenceEventCoordinator coordinator class distributes interventions based on the number of events counted over a period of time.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Action_List

array of JSON objects

NA

NA

NA

List (array) of JSON objects, including the values specified in the following parameters: Threshold, Event_Type, Event_To_Broadcast.

 
{
    "Action_List": [
        {
            "Event_To_Broadcast": "Action_Event_1",
            "Event_Type": "COORDINATOR",
            "Threshold": 20
        },
        {
            "Event_To_Broadcast": "Action_Event_2",
            "Event_Type": "COORDINATOR",
            "Threshold": 30
        }
    ],
    "Threshold_Type": "COUNT"
}

Count_Events_For_Num_Timesteps

integer

1

2.15E+00

1

If set to true (1), then the waning effect values, as specified in the Effect_List list of objects for the WaningEffectCombo classes, are added together. If set to false (0), the waning effect values are multiplied. The resulting waning effect value cannot be greater than 1.

 
{
    "Incidence_Counter": {
        "Count_Events_For_Num_Timesteps": 5,
        "Trigger_Condition_List": [
            "PropertyChange"
        ],
        "Node_Property_Restrictions": [
            {
                "Risk": "HIGH"
            }
        ],
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.6,
        "Property_Restrictions_Within_Node": [
            {
                "Accessibility": "YES"
            }
        ]
    }
}

Event_To_Broadcast

string

NA

NA

NA

The action event to occur when the specified trigger value in the Threshold parameter is met. At least one action must be defined for Event_To_Broadcast. The events contained in the list can be built-in events (see Event list for possible events).

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Event_Type

enum

NA

NA

INDIVIDUAL

The type of event to be broadcast. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Action_List": [
        {
            "Event_To_Broadcast": "Action_Event_1",
            "Event_Type": "COORDINATOR",
            "Threshold": 20
        },
        {
            "Event_To_Broadcast": "Action_Event_2",
            "Event_Type": "COORDINATOR",
            "Threshold": 30
        }
    ],
    "Threshold_Type": "COUNT"
}

Incidence_Counter

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the conditions and parameters that must be met for an incidence to be counted. Some of the values are specified in the following parameters: Count_Events_For_Num_Timesteps, Trigger_Condition_List, Node_Property_Restrictions.

 
{
    "Incidence_Counter": {
        "Count_Events_For_Num_Timesteps": 5,
        "Trigger_Condition_List": [
            "PropertyChange"
        ],
        "Node_Property_Restrictions": [
            {
                "Risk": "HIGH"
            }
        ],
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.6,
        "Property_Restrictions_Within_Node": [
            {
                "Accessibility": "YES"
            }
        ]
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information. You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "class": "IncidenceEventCoordinator",
    "Number_Repetitions": 3
}

Responder

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the threshold type, values, and the actions to take when the specified conditions and parameters have been met, as configured in the Incidence_Counter parameter. Some of the values are specified in the following parameters:

  • Threshold_Type

  • Action_List

  • Threshold

  • Event_To_Broadcast

 
{
    "Responder": {
        "Threshold_Type": "COUNT",
        "Action_List": [
            {
                "Threshold": 5,
                "Event_To_Broadcast": "Action_Event_1"
            },
            {
                "Threshold": 10,
                "Event_To_Broadcast": "Action_Event_2"
            }
        ]
    }
}

Threshold

float

0

3.40E+03

0

The threshold value that triggers the specified action for the Event_To_Broadcast parameter. When you use the Threshold parameter you must also use the Event_To_Broadcast parameter.

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Threshold_Type

enum

NA

NA

COUNT

Threshold type. Possible values are:

  • COUNT

  • PERCENTAGE.

 
{
    "Threshold_Type": "COUNT",
    "Action_List": [
        {
            "Threshold": 20,
            "Event_To_Broadcast": "Action_Event_1"
        },
        {
            "Threshold": 30,
            "Event_To_Broadcast": "Action_Event_2"
        }
    ]
}

Timesteps_Between_Repetitions

integer

-1

1000

-1

The repetition interval.

 
{
    "class": "IncidenceEventCoordinator",
    "Number_Repetitions": 3,
    "Timesteps_Between_Repetitions": 6
}

Trigger_Condition_List

array of strings

NA

NA

NA

A list of events that will trigger an intervention.

 
{
    "Trigger_Condition_List": [
        "NewClinicalCase",
        "NewSevereCase"
    ]
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "class": "IncidenceEventCoordinator",
    "Number_Repetitions" : 3,
    "Timesteps_Between_Repetitions" : 6
}
NChooserEventCoordinator

The NChooserEventCoordinator coordinator class is used to distribute an individual-level intervention to exactly N people of a targeted demographic. This contrasts with other event coordinators that distribute an intervention to a percentage of the population, not to an exact count. See the following JSON example and table, which shows all available parameters for this event coordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Ranges_Years

array of JSON objects

NA

NA

NA

A list of age ranges that individuals must be in to qualify for an intervention. Each age range is a JSON object with a minimum and a maximum property. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age. It must have the same number of objects as Num_Targeted_XXX has elements.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Distributions

array of JSON objects

NA

NA

NA

The ordered list of elements defining when, to whom, and how many interventions to distribute.

 
{
    "Distributions": {
        "Start_Day": 10,
        "End_Day": 20,
        "Property_Restrictions_Within_Node": [],
        "Age_Ranges_Years": [
            {
                "Min": 10,
                "Max": 19
            },
            {
                "Min": 40,
                "Max": 49
            }
        ],
        "Num_Targeted": [
            100,
            300
        ]
    }
}

End_Day

float

0

3.40282e+38

3.40E+38

The day to stop distributing the intervention. No interventions are distributed on this day or going forward.

 
{
    "Start_Day": 10,
    "End_Day": 20
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease",
        "Incubation_Period_Override": 1
    }
}

Max

float

0

125

125

This parameter determines the maximum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Min

float

0

125

0

This parameter determines the minimum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Num_Targeted

array of integers

0

2147480000.0

0

The number of individuals to target with the intervention. Note that this value will be scaled up by the population scaling factor equal to Base_Population_Scale_Factor. If using this parameter, Num_Targeted_Males and Num_Targeted_Females must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 40,
            "Max": 49
        }
    ],
    "Num_Targeted": [
        100,
        300
    ]
}

Num_Targeted_Females

array of integers

0

2147480000.0

0

The number of female individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Males to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Num_Targeted_Males

array of integers

0

2147480000.0

0

The number of male individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Females to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Start_Day

float

0

3.40282e+38

0

The day to start distributing the intervention.

 
{
    "Start_Day": 0,
    "End_Day": 100
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config__KP1": "",
        "Event_Coordinator_Config": {
            "class": "NChooserEventCoordinator",
            "Distributions": [{
                "Start_Day": 10,
                "End_Day": 11,
                "Property_Restrictions_Within_Node": [{
                    "QualityOfCare": "Bad"
                }],
                "Age_Ranges_Years": [{
                    "Min": 20,
                    "Max": 40
                }],
                "Num_Targeted": [
                    99999999
                ]
            }],
            "Intervention_Config": {
                "class": "ControlledVaccine",
                "Cost_To_Consumer": 10,
                "Vaccine_Type": "AcquisitionBlocking",
                "Vaccine_Take": 1.0,
                "Waning_Config": {
                    "class": "WaningEffectMapLinear",
                    "Initial_Effect": 1.0,
                    "Expire_At_Durability_Map_End": 1,
                    "Durability_Map": {
                        "Times": [
                            0,
                            50,
                            100
                        ],
                        "Values": [
                            1.0,
                            1.0,
                            0.0
                        ]
                    }
                },
                "Distributed_Event_Trigger": "Vaccinated",
                "Expired_Event_Trigger": "VaccineExpired",
                "Duration_To_Wait_Before_Revaccination": 0
            }
        }
    }]
}
NChooserEventCoordinatorHIV

The NChooserEventCoordinatorHIV coordinator class distributes an individual-level intervention to exactly N people of a targeted demographic in HIV simulations. This contrasts with other event coordinators that distribute an intervention to a percentage of the population, not to an exact count. This event coordinator is similar to the NChooserEventCoordinator for other simulation types, but replaces start and end days with start and end years an includes HIV-specific restrictions that individuals must have in order to qualify for the intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Ranges_Years

array of JSON objects

NA

NA

NA

A list of age ranges that individuals must be in to qualify for an intervention. Each age range is a JSON object with a minimum and a maximum property. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age. It must have the same number of objects as Num_Targeted_XXX has elements.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Distributions

array of JSON objects

NA

NA

NA

The ordered list of elements defining when, to whom, and how many interventions to distribute.

 
{
    "Distributions": {
        "Start_Day": 10,
        "End_Day": 20,
        "Property_Restrictions_Within_Node": [],
        "Age_Ranges_Years": [
            {
                "Min": 10,
                "Max": 19
            },
            {
                "Min": 40,
                "Max": 49
            }
        ],
        "Num_Targeted": [
            100,
            300
        ]
    }
}

End_Year

float

1900

2200

2200

The year to stop distributing the intervention. Defines the time period to distribute the intervention along with Start_Year. The intervention is evenly distributed between each time step in the time period.

 
{
    "Start_Year": 1963,
    "End_Year": 1963.5
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease",
        "Incubation_Period_Override": 1
    }
}

Max

float

0

125

125

This parameter determines the maximum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Min

float

0

125

0

This parameter determines the minimum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Num_Targeted

array of integers

0

2147480000.0

0

The number of individuals to target with the intervention. Note that this value will be scaled up by the population scaling factor equal to Base_Population_Scale_Factor. If using this parameter, Num_Targeted_Males and Num_Targeted_Females must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 40,
            "Max": 49
        }
    ],
    "Num_Targeted": [
        100,
        300
    ]
}

Num_Targeted_Females

array of integers

0

2147480000.0

0

The number of female individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Males to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Num_Targeted_Males

array of integers

0

2147480000.0

0

The number of male individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Females to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Start_Year

float

1900

2200

1900

The year to start distributing the intervention. Defines the time period to distribute the intervention along with End_Year. The intervention is evenly distributed between each time step in the time period. To have the intervention applied other than at the beginning of the year, you must enter a decimal value after the year. For example, 2010.5 would have the intervention applied halfway through the year 2010.

 
{
    "Start_Year": 1963,
    "End_Year": 1963.5
}

Target_Disease_State

array of strings

NA

NA

NA

A two-dimensional array of particular disease states. To qualify for the intervention, an individual must have only one of the targeted disease states. An individual must have all of the disease states in the inner array. Possible values are:

  • HIV_Positive

  • HIV_Negative

  • Tested_Positive

  • Tested_Negative

  • Male_Circumcision_Positive

  • Male_Circumcision_Negative

  • Has_Intervention

  • Not_have_Intervention

 
{
    "Target_Disease_State": [
        [
            "HIV_Negative",
            "Not_Have_Intervention"
        ]
    ],
    "Target_Disease_State_Has_Intervention_Name": "Vaccine48"
}

Target_Disease_State_Has_Intervention_Name

string

NA

NA

NA

The name of the intervention to look for in an individual when using Has_Intervention or Not_have_Intervention in Target_Disease_State.

 
{
    "Target_Disease_State": [
        [
            "HIV_Negative",
            "Not_Have_Intervention"
        ]
    ],
    "Target_Disease_State_Has_Intervention_Name": "Vaccine48"
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "NChooserEventCoordinatorHIV",
            "Distributions": [{
                    "Start_Year": 1961,
                    "End_Year": 1961.25,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 40,
                        "Max": 49
                    }],
                    "Num_Targeted": [600000, 300000]
                },
                {
                    "Start_Year": 1963,
                    "End_Year": 1963.5,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 20,
                        "Max": 29
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [400000, 200000],
                    "Num_Targeted_Females": [300000, 100000]
                },
                {
                    "Start_Year": 1965,
                    "End_Year": 1965.25,
                    "Target_Disease_State": [
                        ["HIV_Negative", "Not_Have_Intervention"]
                    ],
                    "Target_Disease_State_Has_Intervention_Name": "Vaccine48",
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 30,
                        "Max": 39
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [600000, 400000, 200000],
                    "Num_Targeted_Females": [500000, 300000, 100000]
                }
            ],
            "Intervention_Config": {
                "class": "ControlledVaccine",
                "Intervention_Name": "Vaccine48",
                "Vaccine_Type": "AcquisitionBlocking",
                "Vaccine_Take": 1.0,
                "Waning_Config": {
                    "class": "WaningEffectMapLinear",
                    "Initial_Effect": 1.0,
                    "Expire_At_Durability_Map_End": 1,
                    "Durability_Map": {
                        "Times": [0, 120, 240, 360],
                        "Values": [0.7, 0.8, 1.0, 0.0]
                    }
                },
                "Distributed_Event_Trigger": "Vaccinated",
                "Expired_Event_Trigger": "VaccineExpired",
                "Duration_To_Wait_Before_Revaccination": 240,
                "Cost_To_Consumer": 10
            }
        }
    }]
}
NChooserEventCoordinatorSTI

The NChooserEventCoordinatorSTI coordinator class distributes an individual-level intervention to exactly N people of a targeted demographic in STI simulations. This contrasts with other event coordinators that distribute an intervention to a percentage of the population, not to an exact count. This event coordinator is similar to the NChooserEventCoordinator for other simulation types, but replaces start and end days with start and end years. See the following JSON example and table, which shows all available parameters for this event coordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Ranges_Years

array of JSON objects

NA

NA

NA

A list of age ranges that individuals must be in to qualify for an intervention. Each age range is a JSON object with a minimum and a maximum property. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age. It must have the same number of objects as Num_Targeted_XXX has elements.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Distributions

array of JSON objects

NA

NA

NA

The ordered list of elements defining when, to whom, and how many interventions to distribute.

 
{
    "Distributions": {
        "Start_Day": 10,
        "End_Day": 20,
        "Property_Restrictions_Within_Node": [],
        "Age_Ranges_Years": [
            {
                "Min": 10,
                "Max": 19
            },
            {
                "Min": 40,
                "Max": 49
            }
        ],
        "Num_Targeted": [
            100,
            300
        ]
    }
}

End_Year

float

1900

2200

2200

The year to stop distributing the intervention. Defines the time period to distribute the intervention along with Start_Year. The intervention is evenly distributed between each time step in the time period.

 
{
    "Start_Year": 1963,
    "End_Year": 1963.5
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease",
        "Incubation_Period_Override": 1
    }
}

Max

float

0

125

125

This parameter determines the maximum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Min

float

0

125

0

This parameter determines the minimum age, in years for individuals to be included in the targeted population. An individual is considered in range if their age is greater than or equal to the minimum age and less than the maximum age, in floating point years of age.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 20,
            "Max": 29
        },
        {
            "Min": 50,
            "Max": 59
        }
    ]
}

Num_Targeted

array of integers

0

2147480000.0

0

The number of individuals to target with the intervention. Note that this value will be scaled up by the population scaling factor equal to Base_Population_Scale_Factor. If using this parameter, Num_Targeted_Males and Num_Targeted_Females must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 40,
            "Max": 49
        }
    ],
    "Num_Targeted": [
        100,
        300
    ]
}

Num_Targeted_Females

array of integers

0

2147480000.0

0

The number of female individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Males to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Num_Targeted_Males

array of integers

0

2147480000.0

0

The number of male individuals to distribute interventions to during this time period. If using this parameter with Num_Targeted_Females to target specific genders, they both must be the same length, and Num_Targeted must be empty.

 
{
    "Age_Ranges_Years": [
        {
            "Min": 10,
            "Max": 19
        },
        {
            "Min": 30,
            "Max": 39
        },
        {
            "Min": 50,
            "Max": 59
        }
    ],
    "Num_Targeted_Males": [
        600000,
        400000,
        200000
    ],
    "Num_Targeted_Females": [
        500000,
        300000,
        100000
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Start_Year

float

1900

2200

1900

The year to start distributing the intervention. Defines the time period to distribute the intervention along with End_Year. The intervention is evenly distributed between each time step in the time period. To have the intervention applied other than at the beginning of the year, you must enter a decimal value after the year. For example, 2010.5 would have the intervention applied halfway through the year 2010.

 
{
    "Start_Year": 1963,
    "End_Year": 1963.5
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "NChooserEventCoordinatorSTI",
            "Distributions": [{
                    "Start_Year": 1961,
                    "End_Year": 1961.25,
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 40,
                        "Max": 49
                    }],
                    "Num_Targeted": [600000, 300000]
                },
                {
                    "Start_Year": 1963,
                    "End_Year": 1963.5,
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 20,
                        "Max": 29
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [400000, 200000],
                    "Num_Targeted_Females": [300000, 100000]
                },
                {
                    "Start_Year": 1965,
                    "End_Year": 1965.25,
                    "Property_Restrictions_Within_Node": [],
                    "Age_Ranges_Years": [{
                        "Min": 10,
                        "Max": 19
                    }, {
                        "Min": 30,
                        "Max": 39
                    }, {
                        "Min": 50,
                        "Max": 59
                    }],
                    "Num_Targeted_Males": [600000, 400000, 200000],
                    "Num_Targeted_Females": [500000, 300000, 100000]
                }
            ],
            "Intervention_Config": {
                "class": "ControlledVaccine",
                "Cost_To_Consumer": 10,
                "Vaccine_Type": "AcquisitionBlocking",
                "Vaccine_Take": 1.0
            }
        }
    }]
}
ReferenceTrackingEventCoordinator

The ReferenceTrackingEventCoordinator coordinator class defines a particular coverage of an individual-level persistent intervention that should be present in a population over time. The coordinator tracks the actual coverage with the desired coverage; it will poll the population of nodes it has been assigned to determine how many people have the distributed intervention. When coverage is less than the desired coverage, it will distribute enough interventions to reach the desired coverage.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

End_Year

float

1900

2200

2200

The final date (year) at which this set of targeted coverages should be applied (expiration).

 
{
    "Start_Year": 1962,
    "End_Year": 1964
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Incubation_Period_Override": 1,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "Outbreak",
            "Num_Cases": 1
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 50,
        "class": "StandardInterventionDistributionEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Min

float

0

3.40282e+38

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Timesteps_Between_Repetitions": 50
}

Time_Value_Map

JSON object

NA

NA

NA

The years (times) and matching values of coverages. This parameter uses InterpolatedValueMap to create a JSON structure containing one array of Times and one for Values, which allows for a time-variable probability that can take on any shape over time. When queried at a simulation year corresponding to one of the listed Times, it returns the corresponding Value. The Times and Values must be of equal length, and can consist of a single value. Times must monotonically increase.

 
{
    "Time_Value_Map": {
        "Times": [
            1960,
            1961,
            1962,
            1963,
            1964
        ],
        "Values": [
            0.25,
            0.375,
            0.4,
            0.4375,
            0.46875
        ]
    }
}

Update_Period

float

1

3650

365

The time between distribution updates.

 
{
    "Update_Period": 30.0
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Year": 1960,
        "Event_Coordinator_Config": {
            "class": "ReferenceTrackingEventCoordinator",
            "Target_Demographic": "ExplicitGender",
            "Target_Gender": "Male",
            "Update_Period": 182,
            "End_Year": 1965,
            "Time_Value_Map": {
                "Times": [1960, 1961, 1962, 1963, 1964],
                "Values": [
                    0.25,
                    0.375,
                    0.4,
                    0.4375,
                    0.46875
                ],
                "Intervention_Config": {
                    "class": "MaleCircumcision",
                    "Cost_To_Consumer": 10.0,
                    "Circumcision_Reduced_Acquire": 0.6,
                    "Distributed_Event_Trigger": "VMMC_1"
                }
            }
        }
    }]
}
ReferenceTrackingEventCoordinatorHIV

The ReferenceTrackingEventCoordinatorHIV coordinator class define a particular coverage of an individual- level intervention that should be present in a population over time for HIV simulations. The coordinator tracks the actual coverage with the desired coverage; it will poll the population of nodes it has been assigned to determine how many people have the distributed intervention. When coverage is less than the desired coverage, it will distribute enough interventions to reach the desired coverage. This coordinator is similar to the ReferenceTrackingEventCoordinator, but adds HIV-specific disease state qualifiers, such that individuals must be in particular disease states to qualify for the intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

End_Year

float

1900

2200

2200

The final date (year) at which this set of targeted coverages should be applied (expiration).

 
{
    "Start_Year": 1962,
    "End_Year": 1964
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Incubation_Period_Override": 1,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "Outbreak",
            "Num_Cases": 1
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 50,
        "class": "StandardInterventionDistributionEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Min

float

0

3.40282e+38

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Disease_State

array of strings

NA

NA

Everyone

An array of particular disease states used in the ReferenceTrackingEventCoordinatorHIV. Possible values are:

  • Everyone

  • HIV_Positive

  • HIV_Negative

  • Tested_Positive

  • Tested_Negative

  • Not_Tested_Or_Tested_Negative

 
{
    "Target_Disease_State": "HIV_Positive"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Timesteps_Between_Repetitions": 50
}

Time_Value_Map

JSON object

NA

NA

NA

The years (times) and matching values of coverages. This parameter uses InterpolatedValueMap to create a JSON structure containing one array of Times and one for Values, which allows for a time-variable probability that can take on any shape over time. When queried at a simulation year corresponding to one of the listed Times, it returns the corresponding Value. The Times and Values must be of equal length, and can consist of a single value. Times must monotonically increase.

 
{
    "Time_Value_Map": {
        "Times": [
            1960,
            1961,
            1962,
            1963,
            1964
        ],
        "Values": [
            0.25,
            0.375,
            0.4,
            0.4375,
            0.46875
        ]
    }
}

Update_Period

float

1

3650

365

The time between distribution updates.

 
{
    "Update_Period": 30.0
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Year": 1960,
        "Event_Coordinator_Config": {
            "class": "ReferenceTrackingEventCoordinatorHIV",
            "Target_Demographic": "ExplicitGender",
            "Target_Gender": "Male",
            "Target_Disease_State": "HIV_Negative",
            "Update_Period": 182,
            "End_Year": 1965,
            "Time_Value_Map": {
                "Times": [1960, 1961, 1962, 1963, 1964],
                "Values": [
                    0.25,
                    0.375,
                    0.4,
                    0.4375,
                    0.46875
                ]
            },
            "Intervention_Config": {
                "class": "MaleCircumcision",
                "Cost_To_Consumer": 10.0,
                "Circumcision_Reduced_Acquire": 0.6,
                "Distributed_Event_Trigger": "VMMC_1"
            }
        }
    }]
}
StandardInterventionDistributionEventCoordinator

The StandardInterventionDistributionEventCoordinator coordinator class distributes an individual-level or node-level intervention to a specified fraction of individuals or nodes within a node set. Recurring campaigns can be created by specifying the number of times distributions should occur and the time between repetitions.

Demographic restrictions such as Demographic_Coverage and Target_Gender do not apply when distributing node-level interventions. The node-level intervention must handle the demographic restrictions.

See the following JSON example and table, which shows all available parameters for this event coordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Individual_Selection_Type

enum

NA

NA

DEMOGRAPHIC_COVERAGE

Defines how the people that pass all of the other target restrictions are selected.

Possible values are:

DEMOCGRAPHIC_COVERAGE

When set, the parameter Demographic_Coverage is used to randomly select a certain percentage of the targeted group.

TARGET_NUM_INDIVIDUALS

When set, the parameter Target_Num_Individuals is used to select exactly that number of people out of the targeted group.

 
{
    "Individual_Selection_Type": "DEMOGRAPHIC_COVERAGE",
    "Demographic_Coverage": 0.75
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the actual intervention to be distributed by this event coordinator.

 
{
    "Intervention_Config": {
        "class": "OutbreakIndividual",
        "Incubation_Period_Override": 1,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Intervention_Config": {
            "class": "Outbreak",
            "Num_Cases": 1
        },
        "Number_Repetitions": 10,
        "Timesteps_Between_Repetitions": 50,
        "class": "StandardInterventionDistributionEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Timesteps_Between_Repetitions": 50
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
        "Event_Name": "Outbreak",
        "class": "CampaignEvent",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 1,
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Demographic_Coverage": 0.005,
            "Intervention_Config": {
                "Outbreak_Source": "PrevalenceIncrease",
                "class": "OutbreakIndividual"
            }
        }
    }]
}
SurveillanceEventCoordinator

Note

This campaign class and associated parameters are currently in beta release and have not yet been fully tested.

The SurveillanceEventCoordinator coordinator class listens for and detects events happening and then responds with broadcasted events when a threshold has been met. This campaign event is typically used with other classes, such as BroadcastCoordinatorEvent, TriggeredEventCoordinator, and DelayEventCoordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Action_List

array of JSON objects

NA

NA

NA

A list of possible actions to take if a particular threshold is met. An action is taken when the specified threshold value is less than the number of incidence counted. If there are multiple actions listed then the action with the highest threshold value, that is also less than the number of incidence counted, is selected. The list cannot be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Coordinator_Name

string

NA

NA

TriggeredEventCoordinator

The unique identifying coordinator name, which is useful with the output report, ReportSurveillanceEventRecorder.csv.

 
{
    "class": "CampaignEvent",
    "Start_Day": 1,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "SurveillanceEventCoordinator",
        "Coordinator_Name": "ACF_Counter",
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Type": "PERIODIC",
            "Counter_Period": 14,
            "Counter_Event_Type": "NODE",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ],
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1
        },
        "Responder": {
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT",
            "Action_List": [
                {
                    "Threshold": 5,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_2"
                },
                {
                    "Threshold": 2,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_4"
                }
            ]
        }
    }
}

Counter_Event_Type

enum

NA

NA

INDIVIDUAL

Type of events that can be included in Trigger_Condition_List. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Counter_Period

float

1

10000

1

When Counter_Type is set to PERIODIC, this is the counter period (in days).

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Counter_Type

enum

NA

NA

PERIODIC

Counter type used for surveillance of events. The counter is triggered by events in Start_Trigger_Condition_List and the counter stops when it receives an event in Stop_Trigger_Condition_List or the listening duration expires. Possible values are:

PERIODIC

Once triggered, events are counted during the period (in days) as set in Counter_Period. At the end of the period, the counter will notify Responder with the data accumulated and then start listening again, continuing forever until it is stopped or the duration expires. For example, if the listening duration is 45 days, Counter_Period is 30, and the counter is triggered on day 20, it will never complete the counter period and trigger the responder.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that are counted.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Duration

float

-1

3.40282e+38

-1

The number of days from when the surveillance event coordinator was created by the campaign event. Once the number of days has passed, the delay event coordinator will unregister for events and expire. The default value of ‘-1’ = never expire.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Event_Type

enum

NA

NA

INDIVIDUAL

The type of event to be broadcast. Possible values are:

  • COORDINATOR

  • INDIVIDUAL

  • NODE

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Incidence_Counter

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the conditions and parameters that must be met for an incidence to be counted. Some of the values are specified in the following parameters: Counter_Type, Counter_Period, Counter_Event_Type, Trigger_Condition_List, Node_Property_Restrictions, Property_Restrictions_Within_Node.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Percentage_Events_To_Count

array of strings

NA

NA

NA

When Threshold_Type equals PERCENTAGE_EVENTS then Percentage_Events_To_Count lists the events that will be counted for the denominator which will then be used with the specified event for Trigger_Condition_List counted for the numerator.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": -1,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 30,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Node_Property_Restrictions": [],
            "Property_Restrictions_Within_Node": [],
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Positive_Event_Node"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 0.5
                }
            ],
            "Percentage_Events_To_Count": [
                "Negative_Event_Node",
                "Positive_Event_Node"
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "PERCENTAGE_EVENTS"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Geographic": "URBAN",
            "Risk": "HIGH"
        },
        {
            "Geographic": "URBAN",
            "Risk": "MEDIUM"
        }
    ]
}

Responded_Event

string

NA

NA

“”

A coordinator event, defined in Custom_Coordinator_Events, that is broadcast if Responder responded. More specifically, at the completion of a counting period, if an action is selected, the action events are broadcast and then the Responded_Event is also broadcast. This allows other event coordinators to react to the action events being broadcast.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Responder

array of JSON objects

NA

NA

NA

List of JSON objects for specifying the threshold type, values, and the actions to take when the specified conditions and parameters have been met, as configured in Incidence_Counter. Some of the values are specified in the following parameters:

  • Action_List

  • Event_To_Broadcast

  • Threshold_Type

  • Threshold

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger event list, as specified in the Custom_Coordinator_Events config parameter, that will start Incidence_Counter counting events. The surveillance event coordinator will keep counting and responding until it gets a stop event, as defined in Stop_Trigger_Condition_List, or the duration of the surveillance event coordinator has expired, as defined in Duration. The list cannot be empty.

 
{
    "class": "CampaignEvent",
    "Start_Day": 1,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "SurveillanceEventCoordinator",
        "Coordinator_Name": "ACF_Counter",
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Type": "PERIODIC",
            "Counter_Period": 14,
            "Counter_Event_Type": "NODE",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ],
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1
        },
        "Responder": {
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT",
            "Action_List": [
                {
                    "Threshold": 5,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_2"
                },
                {
                    "Threshold": 2,
                    "Event_Type": "COORDINATOR",
                    "Event_To_Broadcast": "Ind_Start_SIA_4"
                }
            ]
        }
    }
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The broadcast event list, as specified in the Custom_Coordinator_Events config parameter, that will stop Incidence_Counter counting events. The coordinator can start counting again if it receives a start trigger event. The list can be empty.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Female"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), only individuals that currently reside in their ‘home’ node will be counted.

 
{
    "Target_Residents_Only": 1
}

Threshold

float

0

3.40282e+38

0

The COUNT or PERCENTAGE, as configured with Threshold_Type, threshold value that must be met before and action from Action_List will be considered.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Threshold_Type

enum

NA

NA

COUNT

Threshold type to indicate how Responder handles the count of events from Incidence_Counter and the thresholds in Action_List. Possible values are:

COUNT

A raw count of events. Also, with COUNT, setting the x_Base_Population configuration parameter can affect the number count by changing the population but it could be very indirect.

PERCENTAGE

Counts the number of individuals that meet the restrictions and then to divide the total number of events by this number. Note that it is possible for an individual to emit an event that might not be counted in the denominator if their demographic restriction attributes changed between the time of the emitted event and the time the denominator was counted.

PERCENTAGE_EVENTS

Percentage_Events_To_Count lists the events that will be counted for the denominator, which will then be used with the specified event for Trigger_Condition_List to be counted for the numerator.

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Trigger_Condition_List

array of strings

NA

NA

NA

The list of events to count.The list cannot be empty. The type of events contained in the list is determined by Counter_Event_Type. Depending upon the type, the events must be defined in one of the following configuration parameters:

  • Custom_Coordinator_Events

  • Custom_Individual_Events

  • Custom_Node_Events

 
{
    "Event_Coordinator_Config": {
        "Coordinator_Name": "ACF_Counter",
        "Duration": 30,
        "Incidence_Counter": {
            "Counter_Event_Type": "NODE",
            "Counter_Period": 14,
            "Counter_Type": "PERIODIC",
            "Demographic_Coverage": 1,
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "Node_Event_1",
                "Node_Event_2"
            ]
        },
        "Responder": {
            "Action_List": [
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_2",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 5
                },
                {
                    "Event_To_Broadcast": "Ind_Start_SIA_4",
                    "Event_Type": "COORDINATOR",
                    "Threshold": 2
                }
            ],
            "Responded_Event": "Respond_To_Surveillance",
            "Threshold_Type": "COUNT"
        },
        "Start_Trigger_Condition_List": [
            "Start_ACF"
        ],
        "Stop_Trigger_Condition_List": [
            "Start_SIA_2",
            "Start_SIA_4"
        ],
        "class": "SurveillanceEventCoordinator"
    },
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Start_Day": 1,
    "class": "CampaignEvent"
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Events": [

        {
            "comment": "Broadcast Event to start Surveillance",
            "class": "CampaignEvent",
            "Start_Day": 2,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "BroadcastCoordinatorEvent",
                "Coordinator_Name" : "Coordnator_1",
                "Cost_To_Consumer" : 10,
                "Broadcast_Event" : "Start_ACF"
            }
        },
        {
            "comment": "Triggered by Broadcast_Event, stops itself by broadcasting Start_SIA_X Event",
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "SurveillanceEventCoordinator",
                "Coordinator_Name" : "ACF_Counter",
                "Start_Trigger_Condition_List" : [ "Start_ACF" ],
                "Stop_Trigger_Condition_List" : [ 
                    "Start_SIA_2", 
                    "Start_SIA_4"
                ],
                "Duration" : 30,
                "Incidence_Counter" : {
                    "Counter_Type" : "PERIODIC",
                    "Counter_Period" : 14,
                    "Counter_Event_Type" : "NODE",
                    "Trigger_Condition_List" : ["Node_Event_1","Node_Event_2"],
                    "Node_Property_Restrictions" : [],
                    "Property_Restrictions_Within_Node" : [],
                    "Target_Demographic": "Everyone",
                    "Demographic_Coverage" : 1.0
                },
                "Responder" : {
                    "Responded_Event" : "Respond_To_Surveillance",
                    "Threshold_Type" : "COUNT",
                    "Action_List" :
                    [
                        {
                            "Threshold" : 5,
                            "Event_Type" : "COORDINATOR",
                            "Event_To_Broadcast" : "Ind_Start_SIA_2"
                        },
                        {
                            "Threshold" : 2,
                            "Event_Type" : "COORDINATOR",
                            "Event_To_Broadcast" : "Ind_Start_SIA_4"
                        }
                    ]
                }
            }            
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 3,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 25,
                    "Broadcast_Event" : "Node_Event_1"
                }
            }
        },
               {
            "class": "CampaignEvent",
            "Start_Day": 3,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 25,
                    "Broadcast_Event" : "Node_Event_1"
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 4,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 25,
                    "Broadcast_Event" : "Node_Event_2"
                }
            }
        }
    ],
    "Use_Defaults": 1
}
TriggeredEventCoordinator

Note

This campaign class and associated parameters are currently in beta release and have not yet been fully tested.

The TriggeredEventCoordinator coordinator class listens for trigger events, begins a series of repetitions of intervention distributions, and then broadcasts an event upon completion. This campaign event is typically used with other classes that broadcast and distribute events, such as BroadcastCoordinatorEvent, DelayEventCoordinator, and SurveillanceEventCoordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Completion_Event

array of strings

NA

NA

NA

The completion event list that will be broadcast every time the triggered event coordinator completes a set of repetitions. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "class": "TriggeredEventCoordinator",
        "Coordinator_Name": "1n2_Vaccinator",
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Number_Repetitions": 1,
        "Timesteps_Between_Repetitions": 1,
        "Duration": -1,
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.05,
        "Intervention_Config": {
            "class": "SimpleVaccine",
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "class": "WaningEffectBox",
                "Initial_Effect": 0.59,
                "Box_Duration": 730
            }
        },
        "Completion_Event": "Done_Vaccinating_1n2"
    }
}

Coordinator_Name

string

NA

NA

TriggeredEventCoordinator

The unique identifying coordinator name used to identify the different coordinators in reports.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Duration

float

-1

3.40282e+38

-1

The time period (in days) that the triggered event coordinator is active before it expires. Once the specified duration has been reached the coordinator will expire whether or not it is in the middle of a set of repetitions. The value of -1 (default) equals to never expire.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Intervention_Config

JSON object

NA

NA

NA

The nested JSON of the intervention to be distributed by this event coordinator.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information. You can specify AND and OR combinations of key:value pairs with this parameter.

The following configuration restrictions the intervention to nodes that are urban and high risk or have had the first round treatment and are low risk.

{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_3n4",
        "Coordinator_Name": "3n4_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 2,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Node_Property_Restrictions": [
            {
                "Place": "Urban",
                "Risk": "High"
            },
            {
                "InterventionStatus": "FirstRound",
                "Risk": "Low"
            }
        ],
        "Number_Repetitions": 3,
        "Property_Restrictions_Within_Node": [],
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_3n4"
        ],
        "Stop_Trigger_Condition_List": [
            "Stop_Vaccinating_3n4"
        ],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 10,
        "class": "TriggeredEventCoordinator"
    }
}

Number_Repetitions

integer

-1

10000

1

The number of times an intervention is given, used with Timesteps_Between_Repetitions. A value of -1 implies an infinite number of repetitions.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_3n4",
        "Coordinator_Name": "3n4_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 2,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 3,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_3n4"
        ],
        "Stop_Trigger_Condition_List": [
            "Stop_Vaccinating_3n4"
        ],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 10,
        "class": "TriggeredEventCoordinator"
    }
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Geographic": "URBAN",
            "Risk": "HIGH"
        },
        {
            "Geographic": "URBAN",
            "Risk": "MEDIUM"
        }
    ]
}

Start_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger condition event list that when heard will start a new set of repetitions for the triggered event coordinator. The list cannot be empty. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Stop_Trigger_Condition_List

array of strings

NA

NA

NA

The trigger condition event list that when heard will stop any repetitions for the triggered event coordinator until a start trigger condition event list is received. The list can be empty. The events contained in the list are defined in Custom_Coordinator_Events in the simulation configuration file.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.3228e+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Female"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Timesteps_Between_Repetitions

integer

-1

10000

-1

The repetition interval.

 
{
    "Event_Coordinator_Config": {
        "Completion_Event": "Done_Vaccinating_1n2",
        "Coordinator_Name": "1n2_Vaccinator",
        "Demographic_Coverage": 0.05,
        "Duration": -1,
        "Intervention_Config": {
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "Box_Duration": 730,
                "Initial_Effect": 0.59,
                "class": "WaningEffectBox"
            },
            "class": "SimpleVaccine"
        },
        "Number_Repetitions": 1,
        "Start_Trigger_Condition_List": [
            "Start_Vaccinating_1n2"
        ],
        "Stop_Trigger_Condition_List": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": 1,
        "class": "TriggeredEventCoordinator"
    }
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{    
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 0.25,
                "Intervention_Config": {
                    "class": "OutbreakIndividual",
                    "Incubation_Period_Override": 0,
                    "Antigen": 0,
                    "Genome": 0
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 1, 2 ]
            },
            "Event_Coordinator_Config": {
                "class": "TriggeredEventCoordinator",
                "Coordinator_Name": "1n2_Vaccinator",
                "Start_Trigger_Condition_List": [ "Start_Vaccinating_1n2" ],
                "Stop_Trigger_Condition_List": [],
                "Number_Repetitions": 1,
                "Timesteps_Between_Repetitions": 1,
                "Duration": -1,
                "Target_Demographic": "Everyone",
                "Node_Property_Restrictions": [],
                "Property_Restrictions_Within_Node": [],
                "Demographic_Coverage": 0.05,
                "Intervention_Config": {
                   "class": "SimpleVaccine",
                   "Cost_To_Consumer": 1,
                   "Vaccine_Take": 1,
                   "Vaccine_Type": "AcquisitionBlocking",
                   "Waning_Config": {
                      "class": "WaningEffectBox",
                      "Initial_Effect": 0.59,
                      "Box_Duration": 730
                   }
                },
                "Completion_Event": "Done_Vaccinating_1n2"
            }
        },        
        {
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 1, 2 ]
            },
            "Event_Coordinator_Config": {
                "class": "TriggeredEventCoordinator",
                "Coordinator_Name": "1n2_Party",
                "Start_Trigger_Condition_List": [ "Done_Vaccinating_1n2" ],
                "Stop_Trigger_Condition_List": [],
                "Number_Repetitions": 1,
                "Timesteps_Between_Repetitions": 1,
                "Duration": -1,
                "Target_Demographic": "Everyone",
                "Node_Property_Restrictions": [],
                "Property_Restrictions_Within_Node": [],
                "Demographic_Coverage": 0.05,
                "Intervention_Config": {
                   "class": "BroadcastEvent",
                   "Cost_To_Consumer": 1,
                   "Broadcast_Event" : "Individual_Celebrate_1n2"
                },
                "Completion_Event": "Done_Celebrating_1n2"
            }
        },        
        {
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 3, 4 ]
            },
            "Event_Coordinator_Config": {
                "class": "TriggeredEventCoordinator",
                "Coordinator_Name": "3n4_Party",
                "Start_Trigger_Condition_List": [ "Done_Vaccinating_3n4" ],
                "Stop_Trigger_Condition_List": [],
                "Number_Repetitions": 1,
                "Timesteps_Between_Repetitions": 1,
                "Duration": -1,
                "Target_Demographic": "Everyone",
                "Node_Property_Restrictions": [],
                "Property_Restrictions_Within_Node": [],
                "Demographic_Coverage": 0.05,
                "Intervention_Config": {
                   "class": "BroadcastEvent",
                   "Cost_To_Consumer": 1,
                   "Broadcast_Event" : "Individual_Celebrate_3n4"
                },
                "Completion_Event": "Done_Celebrating_3n4"
            }
        },        
        {
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 3,4 ]
            },
            "Event_Coordinator_Config": {
                "class": "TriggeredEventCoordinator",
                "Coordinator_Name": "3n4_Vaccinator",
                "Start_Trigger_Condition_List": [ "Start_Vaccinating_3n4" ],
                "Stop_Trigger_Condition_List": ["Stop_Vaccinating_3n4"],
                "Number_Repetitions": 1,
                "Timesteps_Between_Repetitions": 11,
                "Duration": -1,
                "Target_Demographic": "Everyone",
                "Node_Property_Restrictions": [],
                "Property_Restrictions_Within_Node": [],
                "Demographic_Coverage": 0.05,
                "Intervention_Config": {
                   "class": "SimpleVaccine",
                   "Cost_To_Consumer": 2,
                   "Vaccine_Take": 1,
                   "Vaccine_Type": "AcquisitionBlocking",
                   "Waning_Config": {
                      "class": "WaningEffectBox",
                      "Initial_Effect": 0.59,
                      "Box_Duration": 730
                   }
                },
                "Completion_Event": "Done_Vaccinating_3n4"
            }
        },        
        {
            "class": "CampaignEvent",
            "Start_Day": 5,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 1, 2 ]
            },
            "Event_Coordinator_Config": {
                "class": "BroadcastCoordinatorEvent",
                "Coordinator_Name" : "Start_Coordnator_1n2",
                "Cost_To_Consumer" : 100,
                "Broadcast_Event" : "Start_Vaccinating_1n2"
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 20,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 3, 4 ]
            },
            "Event_Coordinator_Config": {
                "class": "BroadcastCoordinatorEvent",
                "Coordinator_Name" : "Start_Coordnator_3n4",
                "Cost_To_Consumer" : 200,
                "Broadcast_Event" : "Start_Vaccinating_3n4"
            }
        }
    ],
    "Use_Defaults": 1
}
Node-level interventions

Node-level interventions determine what will be distributed to each node to reduce the spread of a disease. For example, spraying larvicide in a village to kill mosquito larvae is a node-level malaria intervention. Sometimes this can be an intermediate intervention that schedules another intervention. Node-level disease outbreaks are also configured as “interventions”. In the schema, these are labeled as NodeTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

BirthTriggeredIV

The BirthTriggeredIV intervention class monitors for birth events and then distributes an actual intervention to the new individuals as specified in Actual_IndividualIntervention_Config.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Config

JSON object

NA

NA

NA

The configuration of an actual individual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Duration

float

-1

3.40282e+38

-1

The number of days to continue this intervention.

Note

For BirthTriggeredIV, specifying a value of -1 results in indefinite persistence of the birth-triggered intervention.

 
{
    "Duration": -1
}

Intervention_Name

string

NA

NA

BirthTriggeredIV

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BirthTriggeredIV",
        "Intervention_Name": "Measles vaccination at 6 months"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Year": 1960,
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "BirthTriggeredIV",
                "Target_Demographic": "ExplicitGender",
                "Target_Gender": "Male",
                "Demographic_Coverage": 1,
                "Actual_IndividualIntervention_Config": {
                    "class": "HIVSigmoidByYearAndSexDiagnostic",
                    "New_Property_Value": "InterventionStatus:None",
                    "Ramp_Min": 0.0,
                    "Ramp_Max": 0.3,
                    "Ramp_MidYear": 2002.0,
                    "Ramp_Rate": 0.5,
                    "Positive_Diagnosis_Event": "HIVNeedsMaleCircumcision"
                }
            }
        }

    }]
}
BroadcastNodeEvent

Note

This campaign class and associated parameters are currently in beta release and have not yet been fully tested.

The BroadcastNodeEvent node intervention class broadcasts node events. This can be used with the campaign class, SurveillanceEventCoordinator, that can monitor and listen for events received from BroadcastNodeEvent and then perform an action based on the broadcasted event. You can also use this for the reporting of the broadcasted events by setting the configuraton parameters, Report_Node_Event_Recorder and Report_Surveillance_Event_Recorder, which listen to events to be recorded. You must use this coordinator class with listeners that are operating on the same core. You can also use NLHTIVNode. For more information, see Simulation core components.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

UNINITIALIZED STRING

The name of the node event to broadcast. This event must be set in the Custom_Node_Events configuration parameter. Note that there are no built-in node events for malaria.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1
        ]
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
            "class": "BroadcastNodeEvent",
            "Cost_To_Consumer": 10,
            "Broadcast_Event": "Node_Event_1"
        }
    }
}

Cost_To_Consumer

float

0

999999

0

The unit cost of the intervention campaign that will be assigned to the specified nodes, as configured under Nodeset_Config.

 
{
    "class": "CampaignEvent",
    "Start_Day": 5,
    "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
            1
        ]
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
            "class": "BroadcastNodeEvent",
            "Cost_To_Consumer": 10,
            "Broadcast_Event": "Node_Event_1"
        }
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

BroadcastNodeEvent

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BroadcastNodeEvent",
        "Intervention_Name": "Mosquito coil repellent"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 0.5,
                "Intervention_Config": {
                    "class": "OutbreakIndividual",
                    "Incubation_Period_Override": 0,
                    "Antigen": 0,
                    "Genome": 0
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 5,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 1 ]
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 10,
                    "Broadcast_Event" : "Node_Event_1"
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 15,
            "Nodeset_Config": {
                "class": "NodeSetNodeList",
                "Node_List": [ 2,3 ]
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 20,
                    "Broadcast_Event" : "Node_Event_2"
                }
            }
        },
        {
            "class": "CampaignEvent",
            "Start_Day": 25,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "BroadcastNodeEvent",
                    "Cost_To_Consumer" : 25,
                    "Broadcast_Event" : "Node_Event_3"
                }
            }
        }
    ],
    "Use_Defaults": 1
}
ImportPressure

The ImportPressure intervention class extends the ImportCases outbreak event. Rather than importing a deterministic number of cases on a scheduled day, ImportPressure applies a set of per-day rates of importation of infected individuals, over a corresponding set of durations. ImportPressure inherits from Outbreak; the Antigen and Genome parameters are defined as they are for all Outbreak events.

Warning

Be careful when configuring import pressure in multi-node simulations. Daily_Import_Pressures defines a rate of per-day importation for each node that the intervention is distributed to. In a 10 node simulation with Daily_Import_Pressures = [0.1, 5.0], the total importation rate summed over all nodes will be 1/day and 50/day during the two time periods. You must divide the per-day importation rates by the number of nodes.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Daily_Import_Pressures

array of floats

0

3.40282e+38

0

The rate of per-day importation for each node that the intervention is distributed to.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Durations": [
            100,
            100,
            100,
            100,
            100,
            100,
            100
        ],
        "Daily_Import_Pressures": [
            0.1,
            5.0,
            0.2,
            1.0,
            2.0,
            0.0,
            10.0
        ],
        "class": "ImportPressure"
    }
}

Durations

array of integers

0

2147480000.0

1

The durations over which to apply import pressure.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Durations": [
            100,
            100,
            100,
            100,
            100,
            100,
            100
        ],
        "Daily_Import_Pressures": [
            0.1,
            5.0,
            0.2,
            1.0,
            2.0,
            0.0,
            10.0
        ],
        "class": "ImportPressure"
    }
}

Genome

integer

0

16777215

0

The genome ID (Genome) of the outbreak infection. Together with the clade ID (Clade) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Genome may range from -1 to 2Log2_Number_of_Genomes_per_Clade-1

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "OutbreakIndividual"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "OutbreakIndividual",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Import_Age

float

0

43800

365

The age (in days) of infected import cases.

 
{
    "Import_Age": 10000
}

Incubation_Period_Override

integer

-1

2147480000.0

-1

The incubation period, in days, that infected individuals will go through before becoming infectious. This value overrides the incubation period set in the configuration file. Set to -1 to honor the configuration parameter settings.

 
{
    "Incubation_Period_Override": 0
}

Number_Cases_Per_Node

integer

0

2147480000.0

1

The number of new cases of Outbreak to import (per node).

Note

This will increase the population and there is no control over demographics of these individuals.

 
{
    "Intervention_Config": {
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "ImportCases",
        "Number_Cases_Per_Node": 10,
        "class": "Outbreak"
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "Initial Seeding",
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Event_Name": "Outbreak",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "Antigen": 0,
                "Genome": 0,
                "Durations": [100, 100, 100, 100, 100, 100, 100],
                "Daily_Import_Pressures": [0.1, 5.0, 0.2, 1.0, 2.0, 0.0, 10.0],
                "class": "ImportPressure"
            }
        }
    }]
}
MigrateFamily

The MigrateFamily intervention class tells family groups of residents of the targeted node to go on a round trip migration (“family trip”). The duration of time residents wait before migration and the time spent at the destination node can be configured; the pre-migration waiting timer does not start until all residents are at the home node.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Duration_At_Node_Constant

float

0

3.40282E+38

-1

The duration at destination node, in days, to use for all families when Duration_At_Node_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Constant": 8
}

Duration_At_Node_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the duration of time an individual or family spends at a destination node after intervention-based migration. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Duration_At_Node_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Duration_At_Node_Max and Duration_At_Node_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Duration_At_Node_Gaussian_Mean and Duration_At_Node_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Duration_At_Node_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Duration_At_Node_Kappa and Duration_At_Node_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Duration_At_Node_Log_Normal_Mu and Duration_At_Node_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Duration_At_Node_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Duration_At_Node_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Duration_At_Node_Mean_1, Duration_At_Node_Mean_2, and Duration_At_Node_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Exponential

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration when Duration_At_Node_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Exponential": 4.25
}

Duration_At_Node_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_At_Node_Gaussian_Mean": 8,
    "Duration_At_Node_Gaussian_Std_Dev": 1.5
}

Duration_At_Node_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_At_Node_Gaussian_Mean": 8,
    "Duration_At_Node_Gaussian_Std_Dev": 1.5
}

Duration_At_Node_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_At_Node_Log_Normal_Mu": 9,
    "Duration_At_Node_Log_Normal_Sigma": 2
}

Duration_At_Node_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_At_Node_Log_Normal_Mu": 9,
    "Duration_At_Node_Log_Normal_Sigma": 2
}

Duration_At_Node_Max

float

0

3.40282E+38

-1

The maximum duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_At_Node_Min": 2,
    "Duration_At_Node_Max": 7
}

Duration_At_Node_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_At_Node_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_At_Node_Min

float

0

3.40282E+38

-1

The minimum duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_At_Node_Min": 2,
    "Duration_At_Node_Max": 7
}

Duration_At_Node_Peak_2_Value

float

0

3.40282E+38

-1

The duration at node value, in days, to assign to the remaining families when Duration_At_Node_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Proportion_0": 0.25,
    "Duration_At_Node_Peak_2_Value": 5
}

Duration_At_Node_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "POISSON_DISTRIBUTION",
    "Duration_At_Node_Poisson_Mean": 5
}

Duration_At_Node_Proportion_0

float

0

1

-1

The proportion of families to assign a value of zero days at node when Duration_At_Node_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Proportion_0": 0.25,
    "Duration_At_Node_Peak_2_Value": 5
}

Duration_At_Node_Proportion_1

float

0

1

-1

The proportion of families in the first exponential distribution when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_Before_Leaving_Constant

float

0

3.40282E+38

-1

The duration before leaving to use for every family, in days, when Duration_Before_Leaving_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Constant": 8
}

Duration_Before_Leaving_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the duration of time an individual or family waits before migrating to the destination node after all residents are home. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Duration_Before_Leaving_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Duration_Before_Leaving_Max and Duration_Before_Leaving_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Duration_Before_Leaving_Gaussian_Mean and Duration_Before_Leaving_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Duration_Before_Leaving_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Duration_Before_Leaving_Kappa and Duration_Before_Leaving_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Duration_Before_Leaving_Log_Normal_Mu and Duration_Before_Leaving_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Duration_Before_Leaving_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Duration_Before_Leaving_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Duration_Before_Leaving_Mean_1, Duration_Before_Leaving_Mean_2, and Duration_Before_Leaving_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Exponential

float

0

3.40282E+38

-1

The mean of the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Exponential": 4.25
}

Duration_Before_Leaving_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_Before_Leaving_Gaussian_Mean": 8,
    "Duration_Before_Leaving_Gaussian_Std_Dev": 1.5
}

Duration_Before_Leaving_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

1

The standard deviation of the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_Before_Leaving_Gaussian_Mean": 8,
    "Duration_Before_Leaving_Gaussian_Std_Dev": 1.5
}

Duration_Before_Leaving_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_Before_Leaving_Kappa": 0.9,
    "Duration_Before_Leaving_Lambda": 1.5
}

Duration_Before_Leaving_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_Before_Leaving_Kappa": 0.9,
    "Duration_Before_Leaving_Lambda": 1.5
}

Duration_Before_Leaving_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_Before_Leaving_Log_Normal_Mu": 9,
    "Duration_Before_Leaving_Log_Normal_Sigma": 2
}

Duration_Before_Leaving_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_Before_Leaving_Log_Normal_Mu": 9,
    "Duration_Before_Leaving_Log_Normal_Sigma": 2
}

Duration_Before_Leaving_Max

float

0

3.40282E+38

-1

The maximum duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Duration_Before_Leaving_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Duration_Before_Leaving_Min

float

0

3.40282E+38

-1

The minimum duration before leaving the home node, in days, when Duration_Before_Leaving_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Peak_2_Value

float

0

3.40282E+38

-1

The duration before leaving the home node to assign to the remaining families, in days, when Duration_Before_Leaving_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Proportion_0": 0.25,
    "Duration_Before_Leaving_Peak_2_Value": 5
}

Duration_Before_Leaving_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the duration before leaving the home node, in days, when Duration_Before_Leaving is set to POISSON_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "POISSON_DISTRIBUTION",
    "Duration_Before_Leaving_Poisson_Mean": 5
}

Duration_Before_Leaving_Proportion_0

float

0

1

-1

The proportion of families to assign a value of zero days before leaving the home node when Duration_Before_Leaving_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Proportion_0": 0.25,
    "Duration_Before_Leaving_Peak_2_Value": 5
}

Duration_Before_Leaving_Proportion_1

float

0

1

-1

The proportion of families in the first exponential distribution when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Intervention_Name

string

NA

NA

MigrateFamily

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MigrateFamily",
        "Intervention_Name": "Move family for seasonal work"
    }
}

Is_Moving

boolean

NA

NA

0

Set to true (1) to indicate the individual is permanently moving to a new home node for intervention-based migration.

 
{
    "Is_Moving": 1
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

NodeID_To_Migrate_To

integer

0

4.29E+09

0

The destination node ID for intervention-based migration.

 
{
    "NodeID_To_Migrate_To": 26
}

{
  "Use_Defaults": 1,
  "Events": [
    {
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "NewInfectionEvent"
          ],
          "Demographic_Coverage": 1.0,
          "Actual_NodeIntervention_Config": {
            "class": "MigrateFamily",
            "NodeID_To_Migrate_To": 4,
            "Duration_Before_Leaving_Distribution": "CONSTANT_DISTRIBUTION",
            "Duration_At_Node_Distribution": "CONSTANT_DISTRIBUTION",
            "Is_Moving": 0,
            "Duration_Before_Leaving_Constant": 0,
            "Duration_At_Node_Constant": 10
          }
        }
      }
    }
  ]
}
MultiNodeInterventionDistributor

The MultiNodeInterventionDistributor intervention class is a node-level intervention that distributes multiple other node-level interventions when the distributor only allows specifying one intervention. This class can be thought of as an “adapter,” where it can adapt interventions or coordinators that were designed to distribute one intervention to instead distribute many.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

MultiNodeInterventionDistributor

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiNodeInterventionDistributor",
        "Intervention_Name": "Country-wide vaccination"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Intervention_List

array of JSON objects

NA

NA

NA

A list of nested JSON objects for the multi-node-level interventions to be distributed by this intervention.

 
{
    "Intervention_Config": {
        "class": "MultiNodeInterventionDistributor",
        "Node_Intervention_List": [
            {
                "class": "SpaceSpraying",
                "Cost_To_Consumer": 1.0,
                "Habitat_Target": "ALL_HABITATS",
                "Spray_Kill_Target": "SpaceSpray_Indoor",
                "Killing_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                },
                "Reduction_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                }
            },
            {
                "class": "NodePropertyValueChanger",
                "Target_NP_Key_Value": "InterventionStatus:RECENT_SPRAY",
                "Daily_Probability": 1.0,
                "Maximum_Duration": 0,
                "Revert": 90
            }
        ]
    }
}

{
    "Intervention_Config": {
        "class": "MultiNodeInterventionDistributor",
        "Node_Intervention_List": [
            {
                "class": "SpaceSpraying",
                "Cost_To_Consumer": 1.0, 
                "Habitat_Target": "ALL_HABITATS", 
                "Spray_Kill_Target": "SpaceSpray_Indoor",
                "Killing_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                        }, 
                "Reduction_Config": {
                    "class": "WaningEffectExponential",
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 90
                        }
            }, 
            {
                "class": "NodePropertyValueChanger",
                "Target_NP_Key_Value": "InterventionStatus:RECENT_SPRAY", 
                "Daily_Probability": 1.0, 
                "Maximum_Duration": 0, 
                "Revert": 90
            }
        ]
    }
}
NodeLevelHealthTriggeredIV

The NodeLevelHealthTriggeredIV intervention class is a node-level intervention that distributes an intervention to individuals when a specific event occurs to those individuals. NodeLevelHealthTriggeredIV monitors for event triggers from individuals, and when found, will distribute the intervention. For example, NodeLevelHealthTriggeredIV can be configured such that all individuals will be given a diagnostic intervention when they transition from susceptible to infectious. During the simulation, when individuals become infected, they broadcast the NewInfectionEvent trigger and NodeLevelHealthTriggeredIV distributes the diagnostic intervention to them.

Notes and tips for this intervention:

  • This is the main tool for distributing an intervention to a person when an event happens to that person. Note that the intervention is distributed to all individuals in the node which experience the triggering event.

  • This is a node-level intervention and is not serialized. If interventions were distributed prior to serialization, in order to have those interventions continue after starting from the serialized file, they must be added to the new campaign file.

  • This can be used to distribute other node-level interventions. For example, it can be used to distribute SpaceSpraying to the node when someone becomes infected (e.g. by listening for for NewInfectionEvent or an event from a diagnostic).

  • A powerful feature of this intervention is that it can target specific groups of individuals who broadcast the event. Individuals, and subgroups of individuals, can be targeted by age, gender, and Individual Property.

  • Note that when distributing a node-level intervention parameters associated with targeting an individual (such as Target_Demographic, Target_Gender, Property_Restriction_Within_Node, etc.) do not apply.

  • Blackout_Period is a feature that can be useful when monitoring an event from the individual in a node. It enables reaction to some individuals experiencing an event but ignoring subsequent events for a period of time. For example, SpaceSpraying could be distributed to the node on the first occurrence of NewInfectionEvent, but after spraying has occurred all other infection events can be ignored for a specific period of time. Without Blackout_Period, each infection event would trigger another round of spraying.

  • The Distribute_On_Return_Home feature causes NodeLevelHealthTriggeredIV to keep track of residents when they leave the node and then return. If a person leaves the node and an intervention is distributed while the person is gone, NodeLevelHealthTriggeredIV gives the person the intervention (such as a vaccine dose) when they return to the node.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Config

JSON object

NA

NA

NA

The configuration of an actual individual intervention to be distributed on the trigger. Selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Actual_NodeIntervention_Config

JSON object

NA

NA

NA

The configuration of the actual node-level intervention sought. This parameter selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_NodeIntervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Blackout_Event_Trigger

enum

NA

NA

NA

The event to broadcast if an intervention cannot be distributed due to the Blackout_Period. See Event list for possible values.

 
{
    "Blackout_Event_Trigger": "Blackout"
}

Blackout_On_First_Occurrence

boolean

NA

NA

0

If set to true (1), individuals will enter the blackout period after the first occurrence of an event in the Trigger_Condition_List.

 
{
    "Blackout_On_First_Occurrence": 0
}

Blackout_Period

float

0

3.40E+38

0

After the initial intervention distribution, the time, in days, to wait before distributing the intervention again. If it cannot distribute due to the blackout period, it will broadcast the user-defined Blackout_Event_Trigger.

 
{
    "Blackout_Period": 0.0
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Distribute_On_Return_Home

boolean

NA

NA

0

When set to true (1), individuals will receive an intervention upon returning home if that intervention was originally distributed while the individual was away.

 
{
    "Distribute_On_Return_Home": 1
}

Duration

float

-1

3.40282e+38

-1

The number of days the NLHTIV will exist and listen for events/triggers.

Note

Specifying a value of -1 results in indefinite persistence of the intervention.

 
{
    "Duration": -1
}

Intervention_Name

string

NA

NA

NodeLevelHealthTriggeredIV

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "NodeLevelHealthTriggeredIV",
        "Intervention_Name": "Treat individuals when infectious"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Max

float

0

9.32E+35

9.32E+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Age_Min

float

0

9.32E+35

0

The lower end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

  • PossibleMothers

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

NA

NA

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Trigger_Condition_List

array of strings

NA

NA

NA

An array of events that will trigger an intervention. The events contained in the list can be built-in events (see Event list for possible events) or the custom events defined in Custom_Individual_Events in the simulation configuration file.

 
{
    "Trigger_Condition_List": [
        "OnART3"
    ]
}

Targeting_Config

JSON object

NA

NA

NA

Be more selective of individuals by using the Targeting_Config classes.

 
{
    "Targeting_Config": {
        "class": "HasIntervention",
        "Is_Equal_To": 0,
        "Intervention_Name": "MyVaccine"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "NodeLevelHealthTriggeredIV",
                "Trigger_Condition_List": ["HappyBirthday"],
                "Demographic_Coverage": 1.0,
                "Target_Age_Max": 99,
                "Target_Age_Min": 21,
                "Target_Demographic": "ExplicitAgeRanges",
                "Target_Residents_Only": 1,
                "Actual_IndividualIntervention_Config": {
                    "class": "OutbreakIndividual",
                    "Antigen": 0,
                    "Genome": 0,
                    "Outbreak_Source": "PrevalenceIncrease"
                }
            }
        }
    }]
}
NodeLevelHealthTriggeredIVScaleUpSwitch

The NodeLevelHealthTriggeredIVScaleUpSwitch intervention class transitions from one intervention to another over time. Generally this is used if one type of diagnostic tool is being phased out but the transition to replace it with the new diagnostic takes place over a few years. The individuals who are included by Demographic_Coverage will receive the new intervention and those that aren’t will receive the older “not covered” intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Config

JSON object

NA

NA

NA

The configuration of an actual individual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Actual_NodeIntervention_Config

JSON object

NA

NA

NA

The configuration of the actual node-level intervention sought. This parameter selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_NodeIntervention_Config": {
        "class": "OutbreakIndividual",
        "Antigen": 0,
        "Genome": 0,
        "Outbreak_Source": "PrevalenceIncrease"
    }
}

Blackout_Event_Trigger

enum

NA

NA

“”

The event to broadcast if an intervention cannot be distributed due to the Blackout_Period. See Event list for possible values.

 
{
    "Blackout_Event_Trigger": "Blackout"
}

Blackout_On_First_Occurrence

boolean

0

1

0

If set to true (1), individuals will enter the blackout period after the first occurrence of an event in the Trigger_Condition_List.

 
{
    "Blackout_On_First_Occurrence": 0
}

Blackout_Period

float

0

3.40282e+38

0

After the initial intervention distribution, the time, in days, to wait before distributing the intervention again. If it cannot distribute due to the blackout period, it will broadcast the user-defined Blackout_Event_Trigger.

 
{
    "Blackout_Period": 0.0
}

Demographic_Coverage

float

0

1

1

The fraction of individuals in the target demographic that will receive this intervention.

 
{
    "Demographic_Coverage": 1
}

Demographic_Coverage_Time_Profile

enum

NA

NA

Immediate

The profile for the ramp-up time to demographic coverage. Possible values are:

  • Immediate

  • Linear

  • Sigmoid

 
{
    "Demographic_Coverage_Time_Profile": "Linear"
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Distribute_On_Return_Home

boolean

0

1

0

When set to true (1), individuals will receive an intervention upon returning home if that intervention was originally distributed while the individual was away.

 
{
    "Distribute_On_Return_Home": 1
}

Duration

float

-1

3.40282e+38

-1

The number of days to continue this intervention.

Note

For BirthTriggeredIV, specifying a value of -1 results in indefinite persistence of the birth-triggered intervention.

 
{
    "Duration": -1
}

Initial_Demographic_Coverage

float

0

1

0

The initial level of demographic coverage when using linear scale-up.

 
{
    "Initial_Demographic_Coverage": 0
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "NodeLevelHealthTriggeredIVScaleUpSwitch",
        "Intervention_Name": "Transition to CDC-recommended diagnostic"
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that nodes must have to be targeted by the intervention. See NodeProperties and IndividualProperties parameters for more information.

You can specify AND and OR combinations of key:value pairs with this parameter.

The following example restricts the intervention to nodes that are urban and medium risk or rural and low risk.

{
    "Node_Property_Restrictions": [
        {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Not_Covered_IndividualIntervention_Configs

array of JSON objects

NA

NA

NA

The array of interventions that is distributed if an individual qualifies according to all parameters except Demographic_Coverage. Generally, this is used to specify a diagnostic tool that is being phased out.

 
{
    "Not_Covered_IndividualIntervention_Configs": [
        {
            "class": "DelayedIntervention",
            "Delay_Distribution": "FIXED_DURATION",
            "Delay_Period": 10,
            "Coverage": 1,
            "Actual_IndividualIntervention_Configs": [
                {
                    "class": "AntiTBDrug",
                    "Cost_To_Consumer": 90,
                    "Drug_Type": "FirstLineCombo",
                    "Durability_Profile": "FIXED_DURATION_CONSTANT_EFFECT",
                    "Primary_Decay_Time_Constant": 180,
                    "Remaining_Doses": 1,
                    "TB_Drug_Cure_Rate": 5e-11,
                    "TB_Drug_Inactivation_Rate": 0
                }
            ]
        }
    ]
}

Primary_Time_Constant

float

0

365000

1

The time to full scale-up demographic coverage.

 
{
    "Primary_Time_Constant": 150
}

Property_Restrictions

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

To specify AND and OR combinations of key:value pairs, use Property_Restrictions_Within_Node. You cannot use both of these parameters in the same event coordinator.

 
{
    "Property_Restrictions": [
        "Risk:HIGH"
    ]
}

Property_Restrictions_Within_Node

array of JSON objects

NA

NA

NA

A list of the IndividualProperty key:value pairs, as defined in the demographics file, that individuals must have to be targeted by this intervention. See NodeProperties and IndividualProperties parameters for more information.

This parameter allows you to specify AND and OR combinations of key:value pairs. You may specify individual property restrictions using either this parameter or Property_Restrictions, but not both.

The following example restricts the intervention to individuals who are urban and high risk or urban and medium risk.

{
    "Property_Restrictions_Within_Node": [
        {
            "Risk": "HIGH",
            "Geographic": "URBAN"
        },
        {
            "Risk": "MEDIUM",
            "Geographic": "URBAN"
        }
    ]
}

Target_Age_Max

float

0

9.3228e+35

9.3228e+35

The upper end of ages targeted for an intervention, in years. Used when Target_Demographic is set to ExplicitAgeRanges or ExplicitAgeRangesAndGender.

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Demographic

enum

NA

NA

Everyone

The target demographic group. Possible values are:

  • Everyone

  • ExplicitAgeRanges

  • ExplicitAgeRangesAndGender

  • ExplicitGender

  • ExplicitDiseaseState

 
{
    "Target_Age_Max": 20,
    "Target_Age_Min": 10,
    "Target_Demographic": "ExplicitAgeRanges"
}

Target_Gender

enum

NA

NA

All

Specifies the gender restriction for the intervention. Possible values are:

  • Male

  • Female

  • All

 
{
    "Target_Gender": "Male"
}

Target_Residents_Only

boolean

0

1

0

When set to true (1), the intervention is only distributed to individuals that began the simulation in the node (i.e. those that claim the node as their residence).

 
{
    "Target_Residents_Only": 1
}

Trigger_Condition_List

array of strings

NA

NA

NA

An array of events that will trigger an intervention. The events contained in the list can be built-in events (see Event list for possible events) or the custom events defined in Custom_Individual_Events in the simulation configuration file.

 
{
    "Trigger_Condition_List": [
        "OnART3"
    ]
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "Illustration of NodeLevelScaleUp: Outbreak to smear- and smear+ at day 100, then diagnostic and treatment of only smear+ cases at day 200",
  "Events": [
    {
      "Event_Name": "when someone broadcasts a positive test using smear, give them the drug",
      "class": "CampaignEvent",
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 99,
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Number_Repetitions": 1,
        "Property_Restrictions": [],
        "Target_Demographic": "Everyone",
        "Timesteps_Between_Repetitions": -1,
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIVScaleUpSwitch",
          "Demographic_Coverage": 1,
          "Demographic_Coverage_Time_Profile": "Linear",
          "Initial_Demographic_Coverage": 0,
          "Primary_Time_Constant": 150,
          "Property_Restrictions_Within_Node": [],
          "Not_Covered_IndividualIntervention_Configs": [
            {
              "class": "DelayedIntervention",
              "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
              "Delay_Period_Constant": 10,
              "Coverage": 1,
              "Actual_IndividualIntervention_Configs": [
                {
                  "class": "SmearDiagnostic",
                  "Base_Sensitivity": 1,
                  "Base_Specificity": 1,
                  "Cost_To_Consumer": 10,
                  "Days_To_Diagnosis": 0,
                  "Treatment_Fraction": 1,
                  "Event_Or_Config": "Event",
                  "Positive_Diagnosis_Event": "TestPositiveOnSmear"
                }
              ]
            }
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "ActiveDiagnostic",
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 8,
            "Days_To_Diagnosis": 0,
            "Treatment_Fraction": 1,
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "TestPositiveOnActive"
          }
        }
      }
    }
  ]
}
NodePropertyValueChanger

The NodePropertyValueChanger intervention class sets a given node property to a new value. You can also define a duration in days before the node property reverts back to its original value, the probability that a node will change its node property to the target value, and the number of days over which nodes will attempt to change their individual properties to the target value. This node-level intervention functions in a similar manner as the individual-level intervention, PropertyValueChanger.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Daily_Probability

float

0

1

1

The daily probability that the node’s property value changes to the Target_NP_Key_Value.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of NodeProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Intervention_Name

string

NA

NA

NodePropertyValueChanger

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Name": "Diagnostic_Sample"
}

Maximum_Duration

float

-1

3.40E+38

3.40E+38

The maximum amount of time in days nodes have to update the property value. This timing works in conjunction with Daily_Probability.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

New_Property_Value

string

NA

NA

NA

An optional NodeProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Revert

float

0

10000

0

The number of days before the node’s property value reverts back to the initial node property value.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Target_NP_Key_Value

string

NA

NA

NA

The NodeProperty key:value pair, as defined in the demographics file, to assign to the node.

 
{
    "Target_NP_Key_Value": "InterventionStatus:NONE"
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEvent",
        "Start_Day": 40,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Node_Property_Restrictions": [{
                "InterventionStatus": "VACCINATING"
            }],
            "Intervention_Config": {
                "class": "NodePropertyValueChanger",
                "Target_NP_Key_Value": "InterventionStatus:STOP_VACCINATING",
                "Daily_Probability": 1.0,
                "Maximum_Duration": 0,
                "Revert": 0
            }
        }
    }]
}
NLHTIVNode

The NLHTIVNode intervention class distributes node-level interventions to nodes when a specific user-defined node event occurs. For example, NLHTIVNode can be configured to have SurveillanceEventCoordinator set to listen for NewInfectionEvents, and then broadcast a node event when a certain number of events is reached, such as distributing IndoorSpaceSpraying to a node with a high number of new infections.

NLHTIVNode is similar to NodeLevelHealthTriggeredIV but NLHTIVNode is focused on node interventions and events while NodeLevelHealthTriggeredIV is focused on individual interventions and events.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_NodeInterventionConfig

JSON object

NA

NA

NA

The configuration of the actual node-level intervention sought. This parameter selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_NodeInterventionConfig": {
        "class": "SpaceSpraying"
        }
}

Blackout_Event_Trigger

string

NA

NA

“

The node event to broadcast if an intervention cannot be distributed due to the Blackout_Period. Custom events can be added; currently the only built-in value is SheddingComplete.

 
{
    "Blackout_Event_Trigger": "SheddingComplete"
}

Blackout_On_First_Occurence

boolean

NA

NA

0

If set to true (1), individuals enter the blackout period after the first occurence of a node event in the Trigger_Condition_List.

 
{
    "Blackout_On_First_Occurence": 0
}

Blackout_Period

float

0

3.40E+38

0

The time in days after the initial intervention distribution to wait before distributing the intervention again. If the intervention is not distributable due to the blackout period, it broadcasts the user-defined Blackout_Event_Trigger.

 
{
    "Blackout_Period": 100.0
}

Duration

float

-1

3.40E+38

-1

The number of days to continue this intervention. A value of -1 keeps the intervention running indefinitely.

 
{
    "Duration": 2723
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Disqualifying_Properties": [
                "InterventionStatus:LostForever"
            ],
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Intervention_Name

string

NA

NA

NLHTIVNode

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Event_Or_Config": "Event",
            "Intervention_Name": "Immunity Blood Test - Series 1",
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "NLHTIVNode"
        }
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Property_Restrictions

JSON object

NA

NA

NA

A list of the NodeProperty key:value pairs, as defined in the demographics file, that are required for nodes to be targeted by the intevention.

 
{
    "Node_Property_Restrictions": [
    {
            "Place": "URBAN",
            "Risk": "MED"
        },
        {
            "Place": "RURAL",
            "Risk": "LOW"
        }
    ]
}

Trigger_Condition_List

array of strings

NA

NA

[ ]

A list of node events that tigger a health-seeking intervention. Currently the only built-in value is SheddingComplete.

 
{
    "Trigger_Condition_List": [
        "SheddingComplete"
    ]
}

{
    "Events": [{
        "comment": "No infections, Negative_Event_Node",
        "class": "CampaignEvent",
        "Start_Day": 1,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "NLHTIVNode",
                "Trigger_Condition_List": ["SheddingComplete"],
                "Duration": 1000,
                "Blackout_Event_Trigger": "Blackout",
                "Blackout_Period": 100.0,
                "Blackout_On_First_Occurrence": 0,
                "Actual_NodeIntervention_Config": {
                    "class": "EnvironmentalDiagnostic",
                    "Sample_Threshold": 0.0,
                    "Environment_IP_Key_Value": "Risk:High",
                    "Base_Specificity": 1.0,
                    "Base_Sensitivity": 1.0,
                    "Negative_Diagnostic_Event": "Negative_Event_Node",
                    "Positive_Diagnostic_Event": "Positive_Event_Node"
                }
            }
        }
    }]
}
Outbreak

The Outbreak class allows the introduction of a disease outbreak event by the addition of new infected or susceptible individuals to a node. Outbreak is a node-level intervention; to distribute an outbreak to specific categories of existing individuals within a node, use OutbreakIndividual.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Clade

integer

0

10

0

The clade ID of the outbreak infection. Together with the genome ID (Genome) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Clade may range from 0 to Number_of_Clades-1 (set in the configuration file).

 
{
    "Clade": 1
}

Genome

integer

-1

1.67E+07

0

The genome ID of the outbreak infection. Together with the clade ID (Clade) they represent an infection as a unitary object. Values for Genome may range from -1 to 2Log2_Number_of_Genomes_per_Clade-1. Set this to -1 to create a random number generator.

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "Outbreak"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Import_Age

float

0

43800

365

The age (in days) of imported individuals.

 
{
    "Import_Age": 10000
}

Number_Cases_Per_Node

integer

0

2.14E+0

1

The number of new imported individuals.

Note

This will increase the population with demographics of 50/50 male/female and user-defined ages.

 
{
    "Intervention_Config": {
        "Clade": 0,
        "Genome": 0,
        "Outbreak_Source": "ImportCases",
        "Number_Cases_Per_Node": 10,
        "class": "Outbreak"
    }
}

Probability_Of_Infection

float

0

1

1

The probability that new individuals are infected. 1.0 implies all new individuals are infected while 0.0 adds all of the people as susceptible individuals.

 
{
    "Probability_Of_Infection": 0.5
}

{
  "Events": [
    {
      "Event_Coordinator_Config": {
        "Demographic_Coverage": 0.001,
        "Intervention_Config": {
          "Clade": 1,
          "Genome": 3,
          "Import_Age": 365,
          "Number_Cases_Per_Node": 10,
          "Probability_Of_Infection": 0.7,
          "class": "Outbreak"
        },
        "Target_Demographic": "Everyone",
        "class": "StandardInterventionDistributionEventCoordinator"
      },
      "Event_Name": "Outbreak",
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 30,
      "class": "CampaignEvent"
    }
  ]
}
Individual-level interventions

Individual-level interventions determine what will be distributed to individuals to reduce the spread of a disease. For example, distributing vaccines or drugs are individual-level interventions. In the schema, these are labeled as IndividualTargeted.

It is also possible (but not required) to configure why a particular intervention is distributed by adding trigger conditions to the intervention. For example, interventions can be triggered by notifications broadcast after some an event, such as Births (the individual’s own birth), GaveBirth, NewInfectionEvent, and more. It’s also possible to have one intervention trigger another intervention by asking the first intervention to broadcast a unique string, and having the second intervention be triggered upon receipt of that string. See Event list.

Individual-level interventions can be used as part of configuring a cascade of care along with the individual properties set in the demographics file. Use Disqualifying_Properties to disqualify individuals who would otherwise receive the intervention and New_Property_Value to assign a new value when the intervention is received. For example, you can assign a property value after receiving the first-line treatment for a disease and prevent anyone from receiving the second-line treatment unless they have that property value and are still symptomatic.

AgeDiagnostic

The AgeDiagnostic intervention class identifies the age threshold of individuals. The minimum and maximum age ranges are configured (for example, 0-5 and 5-20), and the event is based on the resulting age of the individuals. This intervention should be used in conjunction with StandardInterventionDistributionEventCoordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Age_Thresholds

array of JSON objects

NA

NA

NA

Used to associate age ranges for individuals.

 
{
    "class": "AgeDiagnostic",
    "Age_Thresholds": [
        {
            "Low": 0,
            "High": 15,
            "Event": "AgeMeasured0"
        }
    ]
}

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from when test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event

string

NA

NA

“”

The user-defined name of the diagnostic event.

 
{
    "class": "AgeDiagnostic",
    "Age_Thresholds": [
        {
            "Low": 0,
            "High": 15,
            "Event": "AgeMeasured0"
        }
    ]
}

High

float

0

1000

NA

The high end of the age grouping.

 
{
    "class": "AgeDiagnostic",
    "Age_Thresholds": [
        {
            "Low": 0,
            "High": 15,
            "Event": "AgeMeasured0"
        }
    ]
}

Low

float

0

1000

NA

The low end of the age grouping.

 
{
    "class": "AgeDiagnostic",
    "Age_Thresholds": [
        {
            "Low": 0,
            "High": 15,
            "Event": "AgeMeasured0"
        }
    ]
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Use_Defaults": 1,
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 360,
            "Nodeset_Config":
            {
                "class": "NodeSetAll"
            },

            "Event_Coordinator_Config":
            {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1,
                "Intervention_Config":
                {
                    "class": "AgeDiagnostic",
                    "Age_Thresholds": [
                        {
                            "Low": 0,
                            "High": 15,
                            "Event": "AgeMeasured0"
                        },
                        {
                            "NOTE": "Age ranges need not be exclusive.  This event and the next will ffire for a 20 year old.",
                            "Low": 15,
                            "High": 25,
                            "Event": "AgeMeasured1"
                        },
                        {
                            "Low": 15,
                            "High": 50,
                            "Event": "AgeMeasured2"
                        },
                        {
                            "Low": 50,
                            "High": 100,
                            "Event": "AgeMeasured3"
                        }
                    ]
                }
            }
        }
    ]
}
ARTBasic

The ArtBasic intervention class begins antiretroviral therapy (ART) for specified individuals. To remove an individual from ART, use ARTDropout.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

99999

1

The unit cost per drug (unamortized).

 
{
    "Cost_To_Consumer": 10
}

Days_To_Achieve_Viral_Suppression

float

0

3.40282e+38

183

The number of days after ART initiation over which infectiousness declines linearly until the ART_Viral_Suppression_Multiplier takes full effect.

 
{
    "Days_To_Achieve_Viral_Suppression": 0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

ARTBasic

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "ARTBasic",
        "Intervention_Name": "Standard of care"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Viral_Suppression

boolean

0

1

1

If set to true (1), ART will suppress viral load and extend prognosis.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "ARTBasic",
        "Viral_Suppression": 1
    }
}

{
    "Campaign_Name": "ARTBasic intervention test",
    "Use_Defaults": 1,
    "Events": [
        {
            "Description": "New infections get immediate ART",
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": [
                        "NewInfectionEvent"
                    ],
                    "Demographic_Coverage": 1.0,
                    "Actual_IndividualIntervention_Config": {
                        "class": "ARTBasic",
                        "Viral_Suppression": 1,
                        "Days_To_Achieve_Viral_Suppression": 1000000
                    }
                }
            }
        }
    ]
}
ARTDropout

The ARTDropout intervention class removes an individual from antiretroviral therapy (ART) and interrupts their progress through the cascade of care. The individual’s infectiousness will return to a non-suppressed level, and a new prognosis will be assigned.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

99999

1

The unit cost per drug (unamortized).

 
{
    "Cost_To_Consumer": 10
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

ARTDropout

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "ARTDropout",
        "Intervention_Name": "Lost to follow up"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Event_Name": "OnART: state 3 (run ARTDropout)",
        "Start_Year": 1990,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "NodeLevelHealthTriggeredIV",
                "Trigger_Condition_List": [
                    "OnART3"
                ],
                "Actual_IndividualIntervention_Config": {
                    "class": "ARTDropout"
                }
            }
        }
    }]
}
BroadcastEvent

The BroadcastEvent intervention class is an individual-level class that immediately broadcasts the event trigger you specify. This campaign event is typically used with other classes that monitor for a broadcast event, such as NodeLevelHealthTriggeredIV or CommunityHealthWorkerEventCoordinator.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

UNINITIALIZED STRING

The name of the event that will trigger the intervention. See Event list for possible values.

 
{
    "Broadcast_Event": "HIVNeedsHIVTest"
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

BroadcastEvent

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BroadcastEvent",
        "Intervention_Name": "Broadcast that disease treatment was received"
    }
}

New_Property_Value

string

NA

NA

UNINITIALIZED STRING

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "4C: HIVMuxer",
  "Events": [
    {
      "Description": "Drive initial population into a loop",
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "BroadcastEvent",
          "Broadcast_Event": "Loop_Entry_InitialPopulation"
        }
      }
    },
    {
      "Description": "Wait one year, only one entry allowed at a time per individual",
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "Loop_Entry_InitialPopulation",
            "Loop_Entry_Birth",
            "Done_Waiting"
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "HIVMuxer",
            "Disqualifying_Properties": [
              "InterventionStatus:Abort_Infinite_Loop"
            ],
            "New_Property_Value": "InterventionStatus:Infinite_Loop",
            "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
            "Delay_Period_Constant": 365,
            "Muxer_Name": "Delay_Loop_Muxer",
            "Max_Entries": 1,
            "Broadcast_Event": "Done_Waiting"
          }
        }
      }
    }
  ]
}
BroadcastEventToOtherNodes

The BroadcastEventToOtherNodes intervention class allows events to be sent from one node to another. For example, if an individual in one node has been diagnosed, drugs may be distributed to individuals in surrounding nodes.

When this intervention is updated, the event to be broadcast is cached to be distributed to the nodes. After the people have migrated, the event information is distributed to the nodes (i.e. it does support multi-core). During the next time step, the nodes will update their node-level interventions and then broadcast the events from other nodes to ALL the people in the node. This is different from interventions that only broadcast the event in the current node for the person who had the intervention. Distances between nodes use the Longitude and Latitude defined in the demographics file, and use the Haversine Formula for calculating the great-circle distance.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event_Trigger

enum

NA

NA

NA

The name of the event to broadcast to selected nodes. See Event list for possible values.

 
{
    "Event_Trigger": "VaccinateNeighbors"
}

Include_My_Node

boolean

NA

NA

0

Set to true (1) to broadcast the event to the current node.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "BroadcastEventToOtherNodes",
        "Event_Trigger": "VaccinateNeighbors",
        "Include_My_Node": 1,
        "Node_Selection_Type": "DISTANCE_AND_MIGRATION",
        "Max_Distance_To_Other_Nodes_Km": 1
    }
}

Intervention_Name

string

NA

NA

BroadcastEventToOtherNodes

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "BroadcastEventToOtherNodes",
        "Intervention_Name": "Malaria diagnosis triggering reactive case detection"
    }
}

Max_Distance_To_Other_Nodes_Km

float

0

3.40E+38

3.40E+38

The maximum distance, in kilometers, to the destination node for the node to be selected. The location values used are those entered in the demographics file. Used only if Node_Selection_Type is either DISTANCE_ONLY or DISTANCE_AND_MIGRATION.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "BroadcastEventToOtherNodes",
        "Event_Trigger": "VaccinateNeighbors",
        "Include_My_Node": 1,
        "Node_Selection_Type": "DISTANCE_AND_MIGRATION",
        "Max_Distance_To_Other_Nodes_Km": 1
    }
}

New_Property_Value

string

NA

NA

UNITITIALIZED STRING

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Node_Selection_Type

enum

NA

NA

DISTANCE_ONLY

The method by which to select nodes to receive the event. Possible values are:

DISTANCE_ONLY

Nodes located within the distance specified by Max_Distance_To_Other_Nodes_Km are selected.

MIGRATION_NODES_ONLY

Nodes that are local, regional, or connected in the migration file are selected.

DISTANCE_AND_MIGRATION

Nodes are selected using DISTANCE_ONLY and MIGRATION_NODES_ONLY criteria.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "BroadcastEventToOtherNodes",
        "Event_Trigger": "VaccinateNeighbors",
        "Include_My_Node": 1,
        "Node_Selection_Type": "DISTANCE_AND_MIGRATION",
        "Max_Distance_To_Other_Nodes_Km": 1
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
            "Event_Name": "Broadcast to Other Households If Person Infected",
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1,
                "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": ["NewClinicalCase"],
                    "Blackout_Event_Trigger": "Blackout",
                    "Blackout_Period": 0.0,
                    "Blackout_On_First_Occurrence": 0,
                    "Actual_IndividualIntervention_Config": {
                        "class": "BroadcastEventToOtherNodes",
                        "Event_Trigger": "VaccinateNeighbors",
                        "Include_My_Node": 1,
                        "Node_Selection_Type": "DISTANCE_AND_MIGRATION",
                        "Max_Distance_To_Other_Nodes_Km": 1
                    }
                }
            }
        },
        {
            "Event_Name": "Get Vaccinated If Neighbor Infected",
            "class": "CampaignEvent",
            "Start_Day": 0,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1,
                "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": ["VaccinateNeighbors"],
                    "Blackout_Event_Trigger": "Blackout",
                    "Blackout_Period": 0.0,
                    "Blackout_On_First_Occurrence": 0,
                    "Actual_IndividualIntervention_Config": {
                        "class": "AntimalarialDrug",
                        "Cost_To_Consumer": 10,
                        "Dosing_Type": "FullTreatmentParasiteDetect",
                        "Drug_Type": "Chloroquine",
                        "Dont_Allow_Duplicates": 1
                    }
                }
            }
        }
    ]
}
CD4Diagnostic

The CD4Diagnostic intervention class is similar to SimpleDiagnostic, but adds the ability to divide individual populations based on configurable CD4 count ranges. It uses the individual’s current actual CD4 count, regardless of when a CD4 test has been performed. An event can then be applied based on the Low or High group to which the individuals have been moved.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

CD4_Thresholds

array of JSON objects

NA

NA

NA

This parameter associates ranges of CD4 counts with events that should occur for individuals whose CD4 counts fall into those ranges.

 
{
    "Intervention_Config": {
        "class": "CD4Diagnostic",
        "CD4_Thresholds": [
            {
                "Low": 100,
                "High": 500,
                "Event": "CD4Measured0"
            }
        ]
    }
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event

string

NA

NA

“”

The user-defined name of the diagnostic event.

 
{
    "Intervention_Config": {
        "class": "CD4Diagnostic",
        "CD4_Thresholds": [
            {
                "Low": 100,
                "High": 500,
                "Event": "CD4Measured0"
            }
        ]
    }
}

High

float

0

1000

NA

The high end of the diagnostic level.

 
{
    "Intervention_Config": {
        "class": "CD4Diagnostic",
        "CD4_Thresholds": [
            {
                "Low": 100,
                "High": 500,
                "Event": "CD4Measured0"
            }
        ]
    }
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "CD4Diagnostic",
        "Intervention_Name": "Routine test to update ART treatment"
    }
}

Low

float

0

1000

NA

The low end of the diagnostic level.

 
{
    "Intervention_Config": {
        "class": "CD4Diagnostic",
        "CD4_Thresholds": [
            {
                "Low": 100,
                "High": 500,
                "Event": "CD4Measured0"
            }
        ]
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Campaign_Name": "4a_ARTRetention_Depends_on_Time_CD4_Demographics",
    "Default_Campaign_Path": "defaults/hiv_default_campaign.json",
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Event_Name": "",
        "Start_Year": 1990,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "NodeLevelHealthTriggeredIV",
                "Trigger_Condition_List": [
                    "OnART1"
                ],
                "Actual_IndividualIntervention_Config": {
                    "class": "CD4Diagnostic",
                    "CD4_Thresholds": [{
                            "Low": 0,
                            "High": 200,
                            "Event": "OnART4"
                        },
                        {
                            "Low": 200,
                            "High": 100000000,
                            "Event": "OnART7"
                        }
                    ]
                }
            }
        }
    }]
}
ControlledVaccine

The ControlledVaccine intervention class is a subclass of SimpleVaccine so it contains all functionality of SimpleVaccine, but provides more control over additional events and event triggers. This intervention can be configured so that specific events are broadcast when individuals receive an intervention or when the intervention expires. Further, individuals can be re-vaccinated, using a configurable wait time between vaccinations.

Note that one of the controls of this intervention is to not allow a person to receive an additional dose if they received a dose within a certain amount of time. This applies only to ControlledVaccine interventions with the same Intervention_Name, so people can be given multiple vaccines as long as each vaccine has a different value for Intervention_Name.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Distributed_Event_Trigger

enum

NA

NA

NA

The name of the event to be broadcast when the intervention is distributed to an individual. See Event list for possible values. Custom events can be distributed if they are defined in the config parameter Custom_Individual_Events.

 
{
    "Distributed_Event_Trigger": "Vaccinated"
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Duration_To_Wait_Before_Revaccination

float

0

3.40E+38

3.40E+38

The length of time, in days, to wait before revaccinating an individual. After this time has passed, the individual can be revaccinated. If the first vaccine has not expired, the individual can receive the effect from both doses of the vaccine.

 
{
    "Duration_To_Wait_Before_Revaccination": 240
}

Efficacy_Is_Multiplicative

boolean

NA

NA

1

The overall vaccine efficacy when individuals receive more than one vaccine. When set to true (1), the vaccine efficacies are multiplied together; when set to false (0), the efficacies are additive.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Expired_Event_Trigger

enum

NA

NA

NA

The name of the event to be broadcast when the intervention is distributed to an individual. See Event list for possible values. Custom events can be distributed if they are defined in the config parameter Custom_Individual_Events.

 
{
    "Expired_Event_Trigger": "VaccineExpired"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "ControlledVaccine",
        "Intervention_Name": "Round of three measles vaccinations"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Vaccine_Type

enum

NA

NA

Generic

The type of vaccine to distribute in a vaccine intervention. Possible values are:

Generic

The vaccine can reduce transmission, acquisition, and mortality.

TransmissionBlocking

The vaccine will reduce pathogen transmission.

AcquisitionBlocking

The vaccine will reduce the acquisition of the pathogen by reducing the force of infection experienced by the vaccinated individual.

MortalityBlocking

The vaccine reduces the disease-mortality rate of a vaccinated individual.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Waning_Config

JSON object

NA

NA

NA

The configuration of how the intervention efficacy wanes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Waning_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 1,
        "class": "WaningEffectBox"
    }
}

{
    "Use_Defaults": 1,
    "Events": [{
            "COMMENT": "Vaccinate Everyone with VaccineA",
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "class": "ControlledVaccine",
                    "Intervention_Name": "VaccineA",
                    "Cost_To_Consumer": 1,
                    "Vaccine_Type": "AcquisitionBlocking",
                    "Vaccine_Take": 1.0,
                    "Waning_Config": {
                        "class": "WaningEffectMapLinear",
                        "Initial_Effect": 1.0,
                        "Expire_At_Durability_Map_End": 1,
                        "Durability_Map": {
                            "Times": [0, 25, 50],
                            "Values": [1.0, 1.0, 0.0]
                        }
                    },
                    "Distributed_Event_Trigger": "VaccinatedA",
                    "Expired_Event_Trigger": "VaccineExpiredA",
                    "Duration_To_Wait_Before_Revaccination": 40
                }
            }
        },
        {
            "COMMENT": "After the first round expires, distribute a different vaccine, VaccineB",
            "class": "CampaignEvent",
            "Start_Day": 60,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "class": "ControlledVaccine",
                    "Intervention_Name": "VaccineB",
                    "Cost_To_Consumer": 1,
                    "Vaccine_Type": "AcquisitionBlocking",
                    "Vaccine_Take": 1.0,
                    "Waning_Config": {
                        "class": "WaningEffectMapLinear",
                        "Initial_Effect": 1.0,
                        "Expire_At_Durability_Map_End": 1,
                        "Durability_Map": {
                            "Times": [0, 25, 50],
                            "Values": [1.0, 1.0, 0.0]
                        }
                    },
                    "Distributed_Event_Trigger": "VaccinatedB",
                    "Expired_Event_Trigger": "VaccineExpiredB",
                    "Duration_To_Wait_Before_Revaccination": 40
                }
            }
        }
    ]
}
DelayedIntervention

The DelayedIntervention intervention class introduces a delay between when the intervention is distributed to the individual and when they receive the actual intervention. This is due to the frequent occurrences of time delays as individuals seek care and receive treatment. This intervention allows configuration of the distribution type for the delay as well as the fraction of the population that receives the specified intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Configs

array of JSON objects

NA

NA

NA

An array of nested interventions to be distributed at the end of a delay period, to covered fraction of the population.

 
{
    "Actual_IndividualIntervention_Configs": [
        {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Event_Or_Config": "Event",
            "Negative_Diagnosis_Event": "HIVNeedsMaleCircumcision",
            "New_Property_Value": "InterventionStatus:None",
            "Positive_Diagnosis_Event": "NoTreatment",
            "class": "HIVSimpleDiagnostic"
        }
    ]
}

Coverage

float

0

1

1

The proportion of individuals who receive the DelayedIntervention that actually receive the configured interventions. This can be useful to target the intervention to a subset of the people that got the delay. To target the subgroup more specifically, distribute a BroadcastEvent and use a NodeLevelHealthTriggeredIV to distributes the desired intervention.

 
{
    "Coverage": 1.0
}

Delay_Period_Constant

float

0

3.40282E+38

-1

The delay period, in days, to use for all interventions when Delay_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Delay_Period_Constant": 8
}

Delay_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Delay_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Delay_Period_Max and Delay_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Delay_Period_Gaussian_Mean and Delay_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Delay_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Delay_Period_Kappa and Delay_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Delay_Period_Log_Normal_Mu and Delay_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Delay_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Delay_Period_Proportion_0 and Peak_2_Value.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Delay_Period_Mean_1, Delay_Period_Mean_2, and Delay_Period_Proportion_1.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Exponential

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Exponential": 4.25
}

Delay_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Max

float

0

3.40282E+38

-1

The maximum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Min

float

0

3.40282E+38

-1

The minimum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Peak_2_Value

float

0

3.40282E+38

-1

The delay period value to assign to the remaining interventions when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the delay period when Delay_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "POISSON_DISTRIBUTION",
    "Delay_Period_Poisson_Mean": 5
}

Delay_Period_Proportion_0

float

0

1

-1

The proportion of interventions to assign a value of zero delay when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Proportion_1

float

0

1

-1

The proportion of interventions in the first exponential distribution when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

DelayedIntervention

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "DelayedIntervention",
        "Intervention_Name": "Treatment one week after diagnostic test"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
  "Campaign_Name": "Initial Seeding",
  "Events": [
    {
      "Event_Name": "Outbreak",
      "class": "CampaignEvent",
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 1,
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 1.0,
        "Intervention_Config": {
          "class": "DelayedIntervention",
          "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
          "Delay_Period_Constant": 25,
          "Actual_IndividualIntervention_Configs": [
            {
              "Outbreak_Source": "PrevalenceIncrease",
              "class": "OutbreakIndividual"
            }
          ]
        }
      }
    },
    {
      "Event_Name": "Outbreak",
      "class": "CampaignEvent",
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 50,
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 1.0,
        "Intervention_Config": {
          "class": "DelayedIntervention",
          "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
          "Delay_Period_Min": 15,
          "Delay_Period_Max": 30,
          "Actual_IndividualIntervention_Configs": [
            {
              "Outbreak_Source": "PrevalenceIncrease",
              "class": "OutbreakIndividual"
            }
          ]
        }
      }
    }
  ],
  "Use_Defaults": 1
}
HIVARTStagingByCD4Diagnostic

The HIVARTStagingByCD4Diagnostic intervention class builds on the HIVSimpleDiagnostic intervention by checking for treatment eligibility based on CD4 count. It uses the lowest-ever recorded CD4 count for that individual, based on the history of past CD4 counts conducted using the HIVDrawBlood intervention. To specify the outcome based on age bins instead of CD4 testing, use HIVARTStagingCD4AgnosticDiagnostic.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

If_Active_TB

JSON object

NA

NA

NA

If the individual’s CD4 is not below the threshold in the Threshold table and the individual has TB (via their IndividualProperties), then the individual’s CD4 will be compared to the CD4 value retrieved from the InterpolatedValueMap matrix based on the current year.

 
{
    "If_Active_TB": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            800,
            600,
            550,
            500
        ]
    }
}

If_Pregnant

JSON object

NA

NA

NA

If the individual does not pass the diagnostic from the Threshold or TB matrices, and the individual is pregnant, then the individual’s CD4 is compared to the value found in the InterpolatedValueMap matrix.

 
{
    "If_Pregnant": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            600,
            500,
            450,
            400
        ]
    }
}

Individual_Property_Active_TB_Key

string

NA

NA

UNINITIALIZED

The IndividualProperty key (‘HasActiveTB’) used to determine whether the individual has TB.

 
{
    "Individual_Property_Active_TB_Key": "HasActiveTB"
}

Individual_Property_Active_TB_Value

string

NA

NA

UNINITIALIZED

The IndividualProperty value (‘Yes’) used to determine whether the individual has TB.

 
{
    "Individual_Property_Active_TB_Value": "YES"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Name": "Diagnostic_Sample"
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Threshold

JSON object

NA

NA

NA

If the individual’s CD4 has ever been below the threshold specified, then the test will be positive.

 
{
    "Threshold": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            500,
            400,
            350,
            300
        ]
    }
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Campaign_Name": "2a_UniversalART",
    "Default_Campaign_Path": "defaults/hiv_default_campaign.json",
    "Use_Defaults": 1,
    "Events": [{
        "class": "CampaignEventByYear",
        "Event_Name": "ARTStaging: state 6 (check eligibility for ART by CD4)",
        "Start_Year": 1990,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "NodeLevelHealthTriggeredIV",
                "Trigger_Condition_List": [
                    "ARTStaging6"
                ],
                "Actual_IndividualIntervention_Config": {
                    "class": "HIVARTStagingByCD4Diagnostic",
                    "Disqualifying_Properties": [
                        "InterventionStatus:LostForever",
                        "InterventionStatus:OnART",
                        "InterventionStatus:LinkingToART",
                        "InterventionStatus:OnPreART",
                        "InterventionStatus:LinkingToPreART"
                    ],
                    "New_Property_Value": "InterventionStatus:ARTStaging",
                    "Threshold": {
                        "Times": [
                            2004,
                            2011.8,
                            2015,
                            2020
                        ],
                        "Values": [
                            200,
                            350,
                            500,
                            1000000
                        ]
                    },
                    "If_Pregnant": {
                        "Times": [
                            2010.34,
                            2015
                        ],
                        "Values": [
                            350,
                            1000
                        ]
                    },
                    "If_Breastfeeding": {
                        "Times": [
                            2004
                        ],
                        "Values": [
                            0
                        ]
                    },
                    "Event_Or_Config": "Event",
                    "Positive_Diagnosis_Event": "LinkingToART0",
                    "Negative_Diagnosis_Event": "LinkingToPreART0"
                }
            }
        }
    }]
}
HIVARTStagingCD4AgnosticDiagnostic

The HIVARTStagingCD4AgnosticDiagnostic intervention class is similar to the HIVARTStagingByCD4Diagnostic intervention, but it uses age bins to specify outcomes instead of the results of CD4 testing.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Adult_By_Pregnant

JSON object

NA

NA

NA

Determines the WHO stage at or above which pregnant adults are eligible for ART. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Adult_By_Pregnant": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            1,
            1,
            1,
            0
        ]
    }
}

Adult_By_TB

JSON object

NA

NA

NA

Determines the WHO stage at or above which adults having active TB (via individual property Has_Active_TB) are eligible for ART. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Adult_By_TB": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            0,
            1,
            1,
            1
        ]
    }
}

Adult_By_WHO_Stage

JSON object

NA

NA

NA

Determines the WHO stage at or above which adults are eligible for ART. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Adult_By_WHO_Stage": {
        "Times": [
            1990,
            1995,
            2000,
            2005
        ],
        "Values": [
            4.1,
            2,
            3,
            4
        ]
    }
}

Adult_Treatment_Age

float

-1

3.40282e+38

5

The age (in years) that delineates adult patients from pediatric patients for the purpose of treatment eligibility. Patients younger than this age may be eligible on the basis of their pediatric patient status.

 
{
    "Adult_Treatment_Age": 25
}

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Child_By_TB

JSON object

NA

NA

NA

Determines the WHO stage at or above which children having active TB (via individual property Has_Active_TB) are eligible for ART. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Child_By_TB": {
        "Times": [
            2004
        ],
        "Values": [
            0
        ]
    }
}

Child_By_WHO_Stage

JSON object

NA

NA

NA

Determines the WHO stage at or above which children are eligible for ART. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Child_By_WHO_Stage": {
        "Times": [
            2010,
            2011.8
        ],
        "Values": [
            3,
            2
        ]
    }
}

Child_Treat_Under_Age_In_Years_Threshold

JSON object

NA

NA

NA

Determines the age at which children are eligible for ART regardless of CD4, WHO stage, or other factors. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years.

 
{
    "Child_Treat_Under_Age_In_Years_Threshold": {
        "Times": [
            2010.34,
            2013.2
        ],
        "Values": [
            1,
            5
        ]
    }
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Individual_Property_Active_TB_Key

string

NA

NA

UNINITIALIZED

The IndividualProperty key (‘HasActiveTB’) used to determine whether the individual has TB.

 
{
    "Individual_Property_Active_TB_Key": "HasActiveTB"
}

Individual_Property_Active_TB_Value

string

NA

NA

UNINITIALIZED

The IndividualProperty value (‘Yes’) used to determine whether the individual has TB.

 
{
    "Individual_Property_Active_TB_Value": "YES"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVARTStagingCD4AgnosticDiagnostic",
        "Intervention_Name": "Low resource setting diagnostic"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "DrawBlood validation",
    "Events": [
        {
            "class": "CampaignEvent",
            "Event_Name": "OnART1-triggered piecewise event",
            "Start_Day": 1,

            "Nodeset_Config":
            {
                "class": "NodeSetAll"
            },

            "Event_Coordinator_Config":
            {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Event_Name": "DrawBlood constant test, broadcasts HIVPositiveHIVTest",
                "Demographic_Coverage": 1,
                "Intervention_Config":
                {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": [ "HIVNeedsHIVTest" ],

                    "Demographic_Coverage": 1,
                    "Duration": 14600,

                    "Actual_IndividualIntervention_Config":
                    {
                        "class"                    : "HIVARTStagingCD4AgnosticDiagnostic",
                        "Positive_Diagnosis_Event" : "HIVPositiveHIVTest",
                        "Base_Specificity"         : 0,
                        "Base_Sensitivity"         : 0,
                        "Cost_To_Consumer"         : 10,
                        "Days_To_Diagnosis"        : 5,
                        "Disqualifying_Properties"             : [ "InterventionStatus:InterventionStatus_1", "InterventionStatus:InterventionStatus_2", "InterventionStatus:InterventionStatus_3" ],
                        "New_Property_Value"            : "InterventionStatus:InterventionStatus_4",
                        "Individual_Property_Active_TB_Key" : "HasActiveTB",
                        "Individual_Property_Active_TB_Value" : "YES",
                        "Adult_Treatment_Age"    : 1865,
                        "Adult_By_WHO_Stage"                       : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                4.1, 2,   3, 4
                            ]
                        },
                        "Adult_By_TB"                              : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                0,   1,   1, 1
                            ]
                        },
                        "Adult_By_Pregnant"                        : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                1,   1,   1, 0
                            ]
                        },
                        "Child_Treat_Under_Age_In_Years_Threshold" : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                1,   2,   5, 3.2
                            ]
                        },
                        "Child_By_WHO_Stage"                       : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                1.1, 1.5, 2, 2.5
                            ]
                        },
                        "Child_By_TB"                              : {
                            "Times": [
                                1990, 1995, 2000, 2005
                            ],
                            "Values": [
                                1,   1,   1, 0
                            ]
                        }
                    }
                }
            }
        }
    ]
}
HIVDelayedIntervention

HIVDelayedIntervention is an intermediate intervention class based on DelayedIntervention, but adds several features that are specific to the HIV model. This intervention provides new types of distributions for setting the delay and also enables event broadcasting after the delay period expires.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The event that should occur at the end of the delay period. See Event list for possible values.

 
{
    "Broadcast_Event": "LTFU0"
}

Broadcast_On_Expiration_Event

string

NA

NA

“”

If the delay intervention expires before arriving at the end of the delay period, this specifies the event that should occur. For example, if loss to follow-up occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until loss to follow up (LTFU). If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate. See the list of available events for possible values. See Event list for possible values.

 
{
    "Broadcast_On_Expiration_Event": "OnART8"
}

Coverage

float

0

1

1

The proportion of individuals who receive the DelayedIntervention that actually receive the configured interventions.

 
{
    "Coverage": 1.0
}

Delay_Period_Constant

float

0

3.40282E+38

-1

The delay period to use for all interventions, in days, when Delay_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Delay_Period_Constant": 8
}

Delay_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Delay_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Delay_Period_Max and Delay_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Delay_Period_Gaussian_Mean and Delay_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Delay_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Delay_Period_Kappa and Delay_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Delay_Period_Log_Normal_Mu and Delay_Period_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Delay_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Delay_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Delay_Period_Mean_1, Delay_Period_Mean_2, and Delay_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Exponential

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Exponential": 4.25
}

Delay_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Max

float

0

3.40282E+38

-1

The maximum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Min

float

0

3.40282E+38

-1

The minimum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Peak_2_Value

float

0

3.40282E+38

-1

The delay period value, in days, to assign to the remaining interventions when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "POISSON_DISTRIBUTION",
    "Delay_Period_Poisson_Mean": 5
}

Delay_Period_Proportion_0

float

0

1

-1

The proportion of interventions to assign a value of zero delay when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Proportion_1

float

0

1

-1

The proportion of interventions in the first exponential distribution when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Expiration_Period

float

0

3.40282e+38

3.40E+38

A fixed time period, in days, after which the Broadcast_On_Expiration_Event occurs instead of the Broadcast_Event. Only applied if the Expiration_Period occurs earlier than the end of the delay period. For example, if loss to follow-up (LTFU) occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until LTFU. If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate.

 
{
    "Expiration_Period": 183
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVDelayedIntervention",
        "Intervention_Name": "Time to return for test results"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "35_HIV_Delayed_Intervention",
  "Events": [
    {
      "class": "CampaignEvent",
      "Event_Name": "LTFU0 broadcasts should proceed the expiration period of 9 days",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
          "class": "HIVDelayedIntervention",
          "Disqualifying_Properties": [],
          "New_Property_Value": "",
          "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
          "Delay_Period_Constant": 8,
          "Expiration_Period": 9,
          "Broadcast_Event": "LTFU0"
        }
      }
    },
    {
      "class": "CampaignEvent",
      "Event_Name": "LTFU1 broadcasts should be truncated by the expiration period of 7 days",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
          "class": "HIVDelayedIntervention",
          "Disqualifying_Properties": [],
          "New_Property_Value": "",
          "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
          "Delay_Period_Constant": 8,
          "Expiration_Period": 7,
          "Broadcast_Event": "LTFU1"
        }
      }
    }
  ]
}
HIVDrawBlood

The HIVDrawBlood intervention class builds on HIVSimpleDiagnostic to represent phlebotomy for CD4 or viral load testing. It allows for a test result to be recorded and used for future health care decisions, but does not intrinsically lead to a health care event. A future health care decision will use this recorded CD4 count or viral load, even if the actual CD4/viral load has changed since last phlebotomy. The result can be updated by distributing another HIVDrawBlood intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Negative_Diagnosis_Event": "PreDebut"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "DrawBlood validation",
  "Events": [
    {
      "class": "CampaignEvent",
      "Event_Name": "starting on day 8, give everyone a repeated 2-day delayed intervention",
      "Start_Day": 8,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
          "class": "HIVDelayedIntervention",
          "Disqualifying_Properties": [
            "InterventionStatus:InterventionStatus_1",
            "InterventionStatus:InterventionStatus_2",
            "InterventionStatus:InterventionStatus_3"
          ],
          "New_Property_Value": "InterventionStatus:InterventionStatus_4",
          "Single_Use": 1,
          "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
          "Delay_Period_Constant": 2,
          "Broadcast_Event": "HIVNeedsHIVTest"
        }
      }
    },
    {
      "class": "CampaignEvent",
      "Event_Name": "DrawBlood event",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Event_Name": "DrawBlood constant test, broadcasts HIVPositiveHIVTest",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition_List": [
            "HIVNeedsHIVTest"
          ],
          "Demographic_Coverage": 1,
          "Duration": 14600,
          "Actual_IndividualIntervention_Config": {
            "class": "HIVDrawBlood",
            "Positive_Diagnosis_Event": "HIVPositiveHIVTest",
            "Base_Specificity": 0,
            "Base_Sensitivity": 0,
            "Cost_To_Consumer": 10,
            "Days_To_Diagnosis": 0,
            "Disqualifying_Properties": [
              "InterventionStatus:InterventionStatus_1",
              "InterventionStatus:InterventionStatus_2",
              "InterventionStatus:InterventionStatus_3"
            ],
            "New_Property_Value": "InterventionStatus:InterventionStatus_4"
          }
        }
      }
    }
  ]
}
HIVMuxer

The HIVMuxer intervention class is a method of placing groups of individuals into a waiting pattern for the next event, and is based on DelayedIntervention. HIVMuxer adds the ability to limit the number of times an individual can be registered with the delay, which ensures that an individual is only provided with the delay one time. For example, without HIVMuxer, an individual could be given an exponential delay twice, effectively doubling the rate of leaving the delay.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The event that should occur at the end of the delay period. See Event list for possible values.

 
{
    "Broadcast_Event": "LTFU0"
}

Broadcast_On_Expiration_Event

string

NA

NA

“”

If the delay intervention expires before arriving at the end of the delay period, this specifies the event that should occur. For example, if loss to follow-up occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until loss to follow up (LTFU). If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate. See the list of available events for possible values. See Event list for possible values.

 
{
    "Broadcast_On_Expiration_Event": "OnART8"
}

Coverage

float

0

1

1

The proportion of individuals who receive the DelayedIntervention that actually receive the configured interventions.

 
{
    "Coverage": 1.0
}

Delay_Period_Constant

float

0

3.40282E+38

-1

The delay period to use for all interventions, in days, when Delay_Period_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
    "Delay_Period_Constant": 8
}

Delay_Period_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the delay period for distributing interventions. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Delay_Period_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Delay_Period_Max and Delay_Period_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Delay_Period_Gaussian_Mean and Delay_Period_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Delay_Period_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Delay_Period_Kappa and Delay_Period_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and width. Set Delay_Period_Log_Normal_Mean and Delay_Period_Log_Normal_Width.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Delay_Period_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Delay_Period_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Delay_Period_Mean_1, Delay_Period_Mean_2, and Delay_Period_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Exponential

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Exponential": 4.25
}

Delay_Period_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the delay period, in days, when Delay_Period_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Delay_Period_Gaussian_Mean": 8,
    "Delay_Period_Gaussian_Std_Dev": 1.5
}

Delay_Period_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the delay period, in days, when Delay_Period_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "WEIBULL_DISTRIBUTION",
    "Delay_Period_Kappa": 0.9,
    "Delay_Period_Lambda": 1.5
}

Delay_Period_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282e+38

The mean of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the delay period, in days, when Delay_Period_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Delay_Period_Log_Normal_Mu": 9,
    "Delay_Period_Log_Normal_Sigma": 2
}

Delay_Period_Max

float

0

3.40282E+38

-1

The maximum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Delay_Period_Min

float

0

3.40282E+38

-1

The minimum delay period, in days, when Delay_Period_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "UNIFORM_DISTRIBUTION",
    "Delay_Period_Min": 2,
    "Delay_Period_Max": 7
}

Delay_Period_Peak_2_Value

float

0

3.40282E+38

-1

The delay period value to assign to the remaining interventions, in days, when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the delay period, in days, when Delay_Period_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "POISSON_DISTRIBUTION",
    "Delay_Period_Poisson_Mean": 5
}

Delay_Period_Proportion_0

float

0

1

-1

The proportion of interventions to assign a value of zero delay when Delay_Period_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Delay_Period_Proportion_0": 0.25,
    "Delay_Period_Peak_2_Value": 5
}

Delay_Period_Proportion_1

float

0

1

-1

The proportion of interventions in the first exponential distribution when Delay_Period_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Delay_Period_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Delay_Period_Mean_1": 4,
    "Delay_Period_Mean_2": 12,
    "Delay_Period_Proportion_1": 0.2
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Expiration_Period

float

0

3.40282e+38

3.40E+38

A fixed time period, in days, after which the Broadcast_On_Expiration_Event occurs instead of the Broadcast_Event. Only applied if the Expiration_Period occurs earlier than the end of the delay period. For example, if loss to follow-up (LTFU) occurs at a high rate for the first 6 months of care, and then later transitions to a lower rate, then the Expiration_Period should be set to 183 days and Broadcast_On_Expiration_Event can link to another delay intervention with a longer average delay time until LTFU. If LTFU does not occur in the first 6 months, then the expiration will allow the first rate to give way to the post-6-month rate.

 
{
    "Expiration_Period": 183
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVMuxer",
        "Intervention_Name": "Delay for clinic care"
    }
}

Max_Entries

integer

0

2147480000.0

1

The maximum number of times the individual can be registered with the HIVMuxer delay. Determines what should happen if an individual reaches the HIVMuxer stage of health care multiple times. For example, registering for an exponential delay two times effectively doubles the rate of leaving the delay. Setting Max_Entries to 1 prevents the rate from doubling.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "HIVMuxer",
        "Muxer_Name": "ARTDropoutDelay",
        "Max_Entries": 1
    }
}

Muxer_Name

string

NA

NA

NA

A name used to identify the delay and check whether individuals have entered it multiple times. If the same name is used at multiple points in the health care process, then the number of entries is combined when Max_Entries is applied.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "HIVMuxer",
        "Muxer_Name": "ARTDropoutDelay",
        "Max_Entries": 1
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "4C: HIVMuxer",
  "Events": [
    {
      "Description": "Drive initial population into a loop",
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "BroadcastEvent",
          "Broadcast_Event": "Loop_Entry_InitialPopulation"
        }
      }
    },
    {
      "Description": "Drive births into the same loop",
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "BirthTriggeredIV",
          "Actual_IndividualIntervention_Config": {
            "class": "BroadcastEvent",
            "Broadcast_Event": "Loop_Entry_Birth"
          }
        }
      }
    },
    {
      "Description": "Attempt to drive entire population into loop again, HIVMuxer should disallow entry",
      "class": "CampaignEvent",
      "Start_Day": 1095,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "BroadcastEvent",
          "Broadcast_Event": "Loop_Entry_InitialPopulation"
        }
      }
    },
    {
      "Description": "Wait one year, only one entry allowed at a time per individual",
      "class": "CampaignEvent",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config": {
          "class": "NodeLevelHealthTriggeredIV",
          "Trigger_Condition": "TriggerList",
          "Trigger_Condition_List": [
            "Loop_Entry_InitialPopulation",
            "Loop_Entry_Birth",
            "Done_Waiting"
          ],
          "Actual_IndividualIntervention_Config": {
            "class": "HIVMuxer",
            "Disqualifying_Properties": [
              "InterventionStatus:Abort_Infinite_Loop"
            ],
            "New_Property_Value": "InterventionStatus:Infinite_Loop",
            "Delay_Period_Distribution": "CONSTANT_DISTRIBUTION",
            "Delay_Period_Constant": 365,
            "Muxer_Name": "Delay_Loop_Muxer",
            "Max_Entries": 1,
            "Broadcast_Event": "Done_Waiting"
          }
        }
      }
    }
  ]
}
HIVPiecewiseByYearandSexDiagnostic

The HIVPiecewiseByYearAndSexDiagnostic intervention class builds on HIVSimpleDiagnostic to configure the roll-out of an intervention over time. Unlike HIVSigmoidByYearAndSexDiagnostic, which requires the time trend to have a sigmoid shape, this intervention allows for any trend of time to be configured using piecewise or linear interpolation. The trends over time can be configured differently for males and females. Note that the term “diagnosis” is used because this builds on the diagnostic classes in EMOD. However, this intervention is typically used not like a clinical diagnostic, but more like a trend in behavior or coverage over time.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Specificity": 0.95,
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.95,
    "Base_Sensitivity": 0.8
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Default_Value

float

0

1

0

The probability of positive diagnosis if the intervention is used before the earliest specified time in the Time_Value_Map.

 
{
    "Default_Value": 0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Female_Multiplier

float

0

3.40282e+38

1

Allows for the probabilities in the Time_Value_Map to be different for males and females, by multiplying the female probabilities by a constant value.

 
{
    "Female_Multiplier": 1.3
}

Interpolation_Order

integer

0

1

0

When set to zero, interpolation between values in the Time_Value_Map is zero-order (‘staircase’). When set to 1, interpolation between values in the Time_Value_Map is linear. The final value is held constant for all times after the last time specified in the Time_Value_Map.

 
{
    "Interpolation_Order": 0
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVPiecewiseByYearAndSexDiagnostic",
        "Intervention_Name": "Change in health-seeking behavior"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Times

array of floats

0

999999

NA

An array of years.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

Time_Value_Map

JSON object

NA

NA

NA

The years (times) and matching probabilities for test results. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years. This creates a JSON structure containing one array of Times and one for Values, which allows for a time-variable probability that can take on any shape over time. When queried at a simulation year corresponding to one of the listed Times, it returns the corresponding Value. When queried earlier than the first listed Time, it returns the default Value. When queried in between listed Times, it either returns the Value for the most recent past time (when Interpolation_Order is 0) or linearly interpolates Values between Times (when Interpolation_Order is 1). When queried after the last Time in the list, it returns the last Value. The Times and Values must be of equal length, and can consist of a single value. Times must monotonically increase.

 
{
    "Time_Value_Map": {
        "Times": [
            1998,
            2000,
            2003,
            2006,
            2009
        ],
        "Values": [
            0,
            0.26,
            0.08,
            0.14,
            0.54
        ]
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}

{
    "Campaign_Name": "4b_ImprovedRetention_To_BloodDraw",
    "Default_Campaign_Path": "defaults/hiv_default_campaign.json",
    "Use_Defaults": 1,
    "Events": [
        {
            "class": "CampaignEventByYear",
            "Event_Name": "ARTStaging: state 5 (random choice: Return for CD4 or LTFU)",
            "Start_Year": 1990,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": [
                        "ARTStaging5"
                    ],
                    "Actual_IndividualIntervention_Config": {
                        "class": "HIVPiecewiseByYearAndSexDiagnostic",
                        "Disqualifying_Properties": [
                            "InterventionStatus:LostForever",
                            "InterventionStatus:OnART",
                            "InterventionStatus:LinkingToART",
                            "InterventionStatus:OnPreART",
                            "InterventionStatus:LinkingToPreART"
                        ],
                        "New_Property_Value": "InterventionStatus:ARTStaging",
                        "Days_To_Diagnosis": 0,
                        "Default_Value": 0,
                        "Time_Value_Map": {
                            "Times": [
                                1990,
                                2020
                            ],
                            "Values": [
                                0.85,
                                0.9
                            ]
                        },
                        "Interpolation_Order": 0,
                        "Event_Or_Config": "Event",
                        "Positive_Diagnosis_Event": "ARTStaging6",
                        "Negative_Diagnosis_Event": "HCTUptakePostDebut9"
                    }
                }
            }
        }
    ]
}
HIVRandomChoice

The HIVRandomChoice intervention class is based on SimpleDiagnostic, but adds parameters to change the logic in how and where treatment is applied to individuals based on specified probabilities.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Choice_Names

array of strings

NA

NA

[]

An array of event names to be broadcast if randomly selected, used with Choice_Probabilities.

 
{
    "Choice_Names": [
        "ARTStaging12",
        "OnART0"
    ],
    "Choice_Probabilities": [
        0.2,
        0.8
    ]
}

Choice_Probabilities

array of floats

[]

An array of probabilities that the event will be selected, used with Choice_Names. Values in map must be normalized to sum to one.

 
{
    "Choice_Names": [
        "ARTStaging12",
        "OnART0"
    ],
    "Choice_Probabilities": [
        0.2,
        0.8
    ]
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event

string

NA

NA

“”

The name of the event to be broadcast if randomly selected. This parameter part of an event-probability pair, which is configured under the Choices parameter.

 
{
    "New_Property_Value": "InterventionStatus:TestingOnSymptomatic",
    "Event_Or_Config": "Event",
    "Choices": {
        "LTFU3": 0,
        "ARTStaging0": 1
    }
}

Intervention_Name

string

NA

NA

HIVRandomChoice

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVRandomChoice",
        "Intervention_Name": "Probabilistic HIV diagnostic"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Probability

float

0

1

NA

The probability that the event will be selected. Values in map will be normalized. This parameter is part of an event-probability pair, which is configured under the Choices parameter.

 
{
    "New_Property_Value": "InterventionStatus:TestingOnSymptomatic",
    "Event_Or_Config": "Event",
    "Choices": {
        "LTFU3": 0,
        "ARTStaging0": 1
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
  "Use_Defaults": 1,
  "Campaign_Name": "RandomChoice validation",
  "Events": [
    {
      "class": "CampaignEvent",
      "Event_Name": "RandomChoice event",
      "Start_Day": 1,
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Demographic_Coverage": 1,
        "Intervention_Config": {
          "class": "HIVRandomChoice",
          "Days_To_Diagnosis": 0,
          "Event_Or_Config": "Event",
          "Disqualifying_Properties": [],
          "New_Property_Value": "InterventionStatus:None",
          "Choice_Names": [
            "OnART1",
            "OnART2",
            "OnART4",
            "OnART5"
          ],
          "Choice_Probabilities": [
            0.1,
            0.2,
            0.3,
            0.4
          ]
        }
      }
    }
  ]
}
HIVRapidHIVDiagnostic

The HIVRapidHIVDiagnostic intervention class builds on HIVSimpleDiagnostic by also updating the individual’s knowledge of their HIV status. This can affect their access to ART in the future as well as other behaviors. This intervention should be used only if the individual’s knowledge of their status should impact a voluntary male circumcision campaign.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVRapidHIVDiagnostic",
        "Intervention_Name": "Mobile HIV diagnosis campaign"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Probability_Received_Result

float

0

1

1

The probability that an individual received the results of a diagnostic test.

 
{
    "Probability_Received_Result": 0.9
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "Generic HIV Outbreak",
    "Events": [{
        "class": "CampaignEvent",
        "Event_Name": "Test for HIV",
        "Start_Day": 0,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "Intervention_Config": {
                "class": "HIVRapidHIVDiagnostic",
                "Days_To_Diagnosis": 1,
                "Probability_Received_Result": 0.9,
                "Disqualifying_Properties": [],
                "New_Property_Value": "",
                "Positive_Diagnosis_Event": "HCTTestingLoop2",
                "Negative_Diagnosis_Event": "HCTTestingLoop3"
            },
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1.0,
            "Number_Repetitions": 35,
            "Timesteps_Between_Repetitions": 200,
            "class": "StandardInterventionDistributionEventCoordinator",
            "Travel_Linked": 0
        }
    }]
}
HIVSigmoidByYearAndSexDiagnostic

The HIVSigmoidByYearAndSexDiagnostic intervention class builds on HIVSimpleDiagnostic by allowing the probability of “positive diagnosis” to be configured sigmoidally in time. For a linear approach, use HIVPiecewiseByYearandSexDiagnostic.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Female_Multiplier

float

0

3.40282e+38

1

Allows for the sigmoid time-varying probability to be different for males and females, by multiplying the female probability by a constant value.

 
{
    "Female_Multiplier": 1.3
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVSigmoidByYearAndSexDiagnostic",
        "Intervention_Name": "Sigmoidal HIV diagnostic test"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Ramp_Max

float

-1

1

1

The right asymptote for the sigmoid trend over time.

 
{
    "Ramp_Min": 0.05,
    "Ramp_Max": 0.6,
    "Ramp_MidYear": 2000,
    "Ramp_Rate": 1
}

Ramp_MidYear

float

-3.40282e+38

3.40282e+38

2000

The time of the infection point in the sigmoid trend over time.

 
{
    "Ramp_Min": 0.05,
    "Ramp_Max": 0.6,
    "Ramp_MidYear": 2000,
    "Ramp_Rate": 1
}

Ramp_Min

float

-1

1

1

The left asymptote for the sigmoid trend over time.

 
{
    "Ramp_Min": 0.05,
    "Ramp_Max": 0.6,
    "Ramp_MidYear": 2000,
    "Ramp_Rate": 1
}

Ramp_Rate

float

0

1

1

The slope of the inflection point in the sigmoid trend over time. A Rate of 1 sets the slope to a 25% change in probability per year.

 
{
    "Ramp_Min": 0.05,
    "Ramp_Max": 0.6,
    "Ramp_MidYear": 2000,
    "Ramp_Rate": 1
}

Time_Value_Map

JSON object

NA

NA

NA

The years (times) and matching probabilities for test results. This parameter uses InterpolatedValueMap to define Times (by year) and Values for the history and expected treatment guidelines for future years. This creates a JSON structure containing one array of Times and one for Values, which allows for a time-variable probability that can take on any shape over time. When queried at a simulation year corresponding to one of the listed Times, it returns the corresponding Value. When queried earlier than the first listed Time, it returns the default Value. When queried in between listed Times, it either returns the Value for the most recent past time (when Interpolation_Order is 0) or linearly interpolates Values between Times (when Interpolation_Order is 1). When queried after the last Time in the list, it returns the last Value. The Times and Values must be of equal length, and can consist of a single value. Times must monotonically increase.

 
{
    "Time_Value_Map": {
        "Times": [
            1998,
            2000,
            2003,
            2006,
            2009
        ],
        "Values": [
            0,
            0.26,
            0.08,
            0.14,
            0.54
        ]
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Campaign_Name": "1d_MaleCircumcision_at_Age_18",
    "Default_Campaign_Path": "defaults/hiv_default_campaign.json",
    "Use_Defaults": 1,
    "Events":
    [
        {
            "class": "CampaignEventByYear",
            "Event_Name": "Male circumcision at birth",
            "Start_Year": 1990,
            "Nodeset_Config":
            {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config":
            {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Intervention_Config":
                {
                    "class": "BirthTriggeredIV",
                    "Target_Demographic": "ExplicitGender",
                    "Target_Gender": "Male",
                    "Demographic_Coverage": 1,
                    "Actual_IndividualIntervention_Config":
                    {
                        "class": "HIVSigmoidByYearAndSexDiagnostic",
                        "New_Property_Value": "InterventionStatus:None",
                        "Ramp_Min": 0.0,
                        "Ramp_Max": 0.3,
                        "Ramp_MidYear": 2002.0,
                        "Ramp_Rate": 0.5,
                        "Positive_Diagnosis_Event": "HIVNeedsMaleCircumcision"
                    }
                }
            }
        }
    ]
}
HIVSimpleDiagnostic

The HIVSimpleDiagnostic intervention class is based on the SimpleDiagnostic intervention, but adds the ability to specify outcomes upon both positive and negative diagnosis (whereas SimpleDiagnostic only allows for an outcome resulting from a positive diagnosis). HIVSimpleDiagnostic tests for HIV status without logging the HIV test to the individual’s medical history. To log the HIV test to the medical history, use HIVRapidHIVDiagnostic instead.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "HIVSimpleDiagnostic",
        "Intervention_Name": "HIV test"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative, this specifies an event that may trigger another intervention when the event occurs. Only used when Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Event_Or_Config": "Event",
    "Negative_Diagnosis_Event": "PreDebut"
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Events": [{
        "Event_Coordinator_Config": {
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "Base_Sensitivity": 1,
                "Base_Specificity": 1,
                "Days_to_Diagnosis": 0,
                "Event_or_Config": "Event",
                "Negative_Diagnosis_Event": "HIVNegativeTest",
                "Positive_Diagnosis_Event": "HIVPositiveTest",
                "Treatment_Fraction": 1,
                "class": "HIVSimpleDiagnostic"
            },
            "Number_Distributions": -1,
            "Number_Repetitions": 1,
            "Property_Restrictions": [],
            "Target_Group": "Everyone",
            "Timesteps_Between_Repetitions": 1,
            "class": "StandardInterventionDistributionEventCoordinator"
        },
        "Event_Name": "Test Everyone for HIV",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 2,
        "class": "CampaignEvent"
    }],
    "Use_Defaults": 1
}
ImmunityBloodTest

The ImmunityBloodTest intervention class identifies whether an individual’s immunity meets a specified threshold (as set with the Positive_Threshold_AcquisitionImmunity campaign parameter) and then broadcasts an event based on the results; positive has immunity while negative does not. Note that Base_Sensitivity and Base_Specificity function whether or not the immunity is above the threshold.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Treatment_Fraction": 1,
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "class": "ImmunityBloodTest"
        }
    }
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until diagnosis.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Disqualifying_Properties": [
                "InterventionStatus:LostForever"
            ],
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Dont_Allow_Duplicates": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Enable_IsSymptomatic

boolean

NA

NA

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Intervention_Name

string

NA

NA

ImmunityBloodTest

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Intervention_Name": "Immunity Blood Test - Series 1",
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

If an individual tests negative (does not have immunity), then an individual type event is broadcast; custom individual events can be defined in the config parameter Custom_Individual_Events. This may trigger another intervention when the event occurs.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive (has immunity), then an individual type event is broadcast; custom individual events can be defined in the config parameter Custom_Individual_Events. This may trigger another intervention when the event occurs.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Positive_Threshold_AcquisitionImmunity

float

0

1

1

Specifies the threshold for acquired immunity, where 1 equals 100% immunity and 0 equals 100% susceptible.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated.

 
{
    "Event_Coordinator_Config": {
        "Demographic_Coverage": 1,
        "Intervention_Config": {
            "Base_Sensitivity": 1,
            "Base_Specificity": 1,
            "Cost_To_Consumer": 0,
            "Days_To_Diagnosis": 0,
            "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
            "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
            "Positive_Threshold_AcquisitionImmunity": 0.99,
            "Treatment_Fraction": 1,
            "class": "ImmunityBloodTest"
        }
    }
}

{
    "Events":[{
            "class":"CampaignEvent",
            "Start_Day":14,
            "Nodeset_Config":{
                "class":"NodeSetAll"
            },
            "Event_Coordinator_Config":{
                "class":"StandardInterventionDistributionEventCoordinator",
                "Target_Demographic":"Everyone",
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "Base_Sensitivity": 1.0,
                    "Base_Specificity": 1.0,
                    "Cost_To_Consumer": 0,
                    "Days_To_Diagnosis": 0.0,
                    "Positive_Diagnosis_Event": "TestedPositive_IamImmune",
                    "Negative_Diagnosis_Event": "TestedNegative_IamSusceptible",
                    "Treatment_Fraction": 1.0,
                    "Positive_Threshold_AcquisitionImmunity": 0.99,
                    "class": "ImmunityBloodTest"
                }
            }
        }],
    "Use_Defaults":1
}
IndividualImmunityChanger

The IndividualImmunityChanger intervention class acts essentially as a MultiEffectVaccine, with the exception of how the behavior is implemented. Rather than attaching a persistent vaccine intervention object to an individual’s intervention list (as a campaign-individual-multieffectboostervaccine does), the IndividualImmunityChanger directly alters the immune modifiers of the individual’s susceptibility object and is then immediately disposed of. Any immune waning is not governed by Waning effect classes, as MultiEffectVaccine is, but rather by the immunity waning parameters in the configuration file.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Boost_Acquire

float

0

1

0

Specifies the boosting effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Acquire": 0.7
}

Boost_Mortality

float

0

1

0

Specifies the boosting effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Mortality": 1.0
}

Boost_Threshold_Acquire

float

0

1

0

Specifies how much acquisition immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Acquire": 0.0
}

Boost_Threshold_Mortality

float

0

1

0

Specifies how much mortality immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Mortality": 0.0
}

Boost_Threshold_Transmit

float

0

1

0

Specifies how much transmission immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Transmit": 0.0
}

Boost_Transmit

float

0

1

0

Specifies the boosting effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Transmit": 0.5
}

Cost_To_Consumer

float

0

999999

1

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Prime_Acquire

float

0

1

0

Specifies the priming effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Acquire": 0.1
}

Prime_Mortality

float

0

1

0

Specifies the priming effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Mortality": 0.3
}

Prime_Transmit

float

0

1

0

Specifies the priming effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Transmit": 0.2
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "Generic Seattle Regression Campaign",
    "Events": [{
        "Start_Day": 10,
        "class": "CampaignEvent",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "class": "IndividualImmunityChanger",
                "Cost_To_Consumer": 10.0,
                "Prime_Acquire": 0.1,
                "Prime_Transmit": 0.2,
                "Prime_Mortality": 0.3,
                "Boost_Acquire": 0.7,
                "Boost_Transmit": 0.7,
                "Boost_Mortality": 1.0,
                "Boost_Threshold_Acquire": 0.2,
                "Boost_Threshold_Transmit": 0.1,
                "Boost_Threshold_Mortality": 0.1
            }
        }
    }]
}
InterventionForCurrentPartners

The InterventionForCurrentPartners intervention class provides a mechanism for the partners of individuals in the care system to also seek care. Partners do not need to seek testing at the same time; a delay may occur between the initial test and the partner’s test. If a relationship has been paused, such as when a partner migrates to a different node, the partner will not be contacted.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Broadcast_Event

string

NA

NA

“”

The event that is immediately broadcast to the partner. Required if Event_or_Config is set to Event. See Event list for possible built-in values, or create custom values using Custom_Individual_Events.

 
{
    "Broadcast_Event": "HIVNewlyDiagnosed"
}

Disqualifying_Properties

array of strings

NA

NA

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Event"
}

Intervention_Config

JSON object

The intervention definition that is immediately distributed to the partner. Required if Event_Or_Config is set to Config.

 
{
    "class": "StandardInterventionDistributionEventCoordinator",
    "Intervention_Config": {
        "class": "NodeLevelHealthTriggeredIV",
        "Trigger_Condition_List": [
            "Some_Other_Event"
        ],
        "Actual_IndividualIntervention_Config": {
            "class": "InterventionForCurrentPartners",
            "Disqualifying_Properties": [],
            "New_Property_Value": "CascadeState:TestingCurrentPartner",
            "Relationship_Types": [
                "MARITAL",
                "INFORMAL",
                "TRANSITORY",
                "COMMERCIAL"
            ],
            "Minimum_Duration_Years": 0.5,
            "Prioritize_Partners_By": "LONGER_TIME_IN_RELATIONSHIP",
            "Maximum_Partners": 2,
            "Event_Or_Config": "Event",
            "Broadcast_Event": "HIVNewlyDiagnosed"
        }
    }
}

Intervention_Name

string

NA

NA

InterventionForCurrentPartners

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "Intervention_Name": "Intervention_For_Spouse",
        "class": "InterventionForCurrentPartnersr"
    }
}

Maximum_Partners

integer

0

1000

100

The maximum number of partners that will receive the intervention. Required when Prioritize_Partners_By is not set to NO_PRIORITIZATION.

 
{
    "Prioritize_Partners_By": "NO_PRIORITIZATION",
    "Maximum_Partners": 2
}

Minimum_Duration_Years

float

0

200

0

The minimum amount of time, in years, between relationship formation and the current time for the partner to qualify for the intervention.

 
{
    "Minimum_Duration_Years": 0.5
}

New_Property_Value

string

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prioritize_Partners_By

enum

NA

NA

NO_PRIORITIZATION

How to prioritize partners for the intervention, as long as they have been in a relationship longer than Minimum_Duration_Years. Possible values are:

NO_PRIORTIZATION

All partners are contacted.

CHOSEN_AT_RANDOM

Partners are randomly selected until Maximum_Partners have received the intervention.

LONGER_TIME_IN_RELATIONSHIP

Partners are sorted in descending order of the duration of the relationship. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

SHORTER_TIME_IN RELATIONSHIP

Partners are sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of the list until Maximum_Partners have received the intervention.

OLDER_AGE

Partners are sorted in descending order of their age. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

YOUNGER_AGE

Partners are sorted in ascending order of the duration of the relationship. Partners are contacted from the beginning of this list until Maximum_Partners have received the intervention.

RELATIONSHIP_TYPE

Partners are sorted based on the order of relationship types defined in the Relationship_Types array. For example, “Relationship_Types” : [“MARITAL”, “INFORMAL”, “TRANSITORY”, “COMMERCIAL”], will prioritize marital first, then informal, then transitory, then commercial, with random selection between mulitple partners of the same type.

 
{
    "Prioritize_Partners_By": "LONGER_TIME_IN_RELATIONSHIP"
}

Relationship_Types

array of strings

NA

NA

NA

An array listing all possible relationship types for which partners can qualify for the intervention. Supported partnerships include TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL. If Prioritize_Partners_By is set to RELATIONSHIP_TYPE, then the order of these types is used. The array may not contain duplicates, and cannot be empty.

 
{
    "Relationship_Types": [
        "MARITAL",
        "INFORMAL",
        "TRANSITORY",
        "COMMERCIAL"
    ]
}

{
    "class": "CampaignEvent",
    "Start_Day": 50,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Demographic": "ExplicitGender",
        "Target_Gender": "FEMALE",
        "Demographic_Coverage": 1.0,
        "Intervention_Config": {
            "class": "InterventionForCurrentPartners",
            "Disqualifying_Properties": [],
            "New_Property_Value": "",
            "Minimum_Duration_Years": 0.05,
            "Prioritize_Partners_By": "LONGER_TIME_IN_RELATIONSHIP",
            "Relationship_Types": [],
            "Maximum_Partners": 5,
            "Event_Or_Config": "Config",
            "Intervention_Config": {
                "class": "MaleCircumcision",
                "Circumcision_Reduced_Acquire": 1.0,
                "Distributed_Event_Trigger": "Reduced_Acquire_Lowest",
                "Apply_If_Higher_Reduced_Acquire": 1
            }
        }
    }
}
IVCalendar

The IVCalendar intervention class contains a list of ages when an individual will receive the actual intervention. In IVCalendar, there is a list of actual interventions where the distribution is dependent on whether the individual’s age matches the next date in the calendar. This implies that at a certain age, the list of actual interventions will be distributed according to a given probability. While a typical use case might involve the distribution of calendars by a BirthTriggeredIV in the context of a routine vaccination schedule, calendars may also be distributed directly to individuals.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Configs

array of JSON objects

NA

NA

NA

An array of interventions that will be distributed as specified in the calendar. This parameter selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "IVCalendar",
        "Actual_IndividualIntervention_Configs": [
            {
                "class": "BCGVaccine",
                "Cost_To_Consumer": 10,
                "Vaccine_Take": 1,
                "Vaccine_Take_Age_Decay_Rate": 0,
                "Waning_Config": {
                    "Initial_Effect": 1,
                    "Box_Duration": 3650,
                    "Decay_Rate_Factor": 3650,
                    "class": "WaningEffectBoxExponential"
                }
            }
        ]
    }
}

Calendar

array of JSON objects

NA

NA

[ ]

An array of JSON objects where each object specifies the age and probability of receiving the interventions. The parameters of the Calendar objects are: * Age: The age (in days) that the individual must be in order to receive the list of actual interventions. * Probability: The probability of an individual receiving the list of actual interventions at the corresponding age.

 
{
    "Calendar": [
        {
            "Age": 60,
            "Probability": 1
        },
        {
            "Age": 120,
            "Probability": 1
        },
        {
            "Age": 180,
            "Probability": 1
        },
        {
            "Age": 510,
            "Probability": 0.9
        },
        {
            "Age": 1825,
            "Probability": 0.95
        },
        {
            "Age": 4200,
            "Probability": 0.95
        }
    ]
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Dropout

boolean

NA

NA

0

If set to true (1), when an intervention distribution is missed, all subsequent interventions are also missed. If set to false (0), all calendar dates/doses are applied independently of each other.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "IVCalendar",
        "Dont_Allow_Duplicates": 0,
        "Dropout": 0,
        "Calendar": [
            {
                "Age": 12045,
                "Probability": 1
            }
        ]
    }
}

Intervention_Name

string

NA

NA

IVCalendar

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "IVCalendar",
        "Intervention_Name": "Routine measles vaccination schedule"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "BCG vaccination calendar distributed at birth",
    "Events": [{
        "Event_Name": "BCG vaccinations scheduled at birth",
        "class": "CampaignEvent",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 1825,
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Intervention_Config": {
                "class": "BirthTriggeredIV",
                "Demographic_Coverage": 0.9,
                "Actual_IndividualIntervention_Config": {
                    "class": "IVCalendar",
                    "Calendar": [{
                            "Age": 30,
                            "Probability": 1
                        },
                        {
                            "Age": 3650,
                            "Probability": 1
                        }
                    ],
                    "Dropout": 0,
                    "Actual_IndividualIntervention_Configs": [{
                        "class": "BCGVaccine",
                        "Cost_To_Consumer": 8,
                        "Vaccine_Take": 0.8,
                        "Vaccine_Take_Age_Decay_Rate": 0.2,
                        "Waning_Config": {
                            "Initial_Rate": 0.9,
                            "Decay_Time_Constant": 3650,
                            "class": "WaningEffectExponential"
                        }
                    }]
                }
            }
        }
    }]
}
MaleCircumcision

The MaleCircumcision intervention class introduces male circumcision as a method to control HIV transmission. Voluntary medical male circumcision (VMMC) permanently reduces a male’s likelihood of acquiring HIV; successful distribution results in a reduction in the probability of transmission.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Apply_If_Higher_Reduced_Acquire

boolean

0

1

0

If set to false (0), the MaleCircumcision intervention can never be applied to someone who already has a MaleCircumcision intervention. If set to true (1), a male who already has a MaleCircumcision intervention, but whose pre-existing MaleCircumcision intervention has a lower efficacy parameter (Circumcision_Reduced_Acquire) than the one about to be applied, will receive the higher-efficacy MaleCircumcision.

 
{
    "Apply_If_Higher_Reduced_Acquire": 1
}

Circumcision_Reduced_Acquire

float

0

1

0.6

The reduction of susceptibility to STI by voluntary male medical circumcision (VMMC).

 
{
    "Circumcision_Reduced_Acquire": 0.6
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Distributed_Event_Trigger

string

NA

NA

NA

When defined as part of an intervention block of class MaleCircumcision, this string defines the name of the column in the output files ReportHIVByAgeAndGender.csv and ReportEventRecorder.csv, which log when the intervention has been distributed. See Event list for possible values.

 
{
    "Distributed_Event_Trigger": "VMMC_1"
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MaleCircumcision",
        "Intervention_Name": "Routine voluntary male circumcision"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "HIV 3B: VMMC",
    "Events": [{
        "class": "CampaignEventByYear",
        "Event_Name": "Male circumcision at birth starting in 2025",
        "Start_Year": 2025,
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Intervention_Config": {
                "class": "BirthTriggeredIV",
                "Demographic_Coverage": 1,
                "Target_Demographic": "ExplicitGender",
                "Target_Gender": "Male",
                "Actual_IndividualIntervention_Config": {
                    "class": "MaleCircumcision",
                    "Circumcision_Reduced_Acquire": 0.6
                }
            }
        }
    }]
}
MigrateIndividuals

The MigrateIndividuals intervention class is an individual-level intervention used to force migration and is separate from the normal migration system. However, it does require that human migration is enabled by setting the configuration parameters Migration_Model to FIXED_RATE_MIGRATION and Migration_Pattern to SINGLE_ROUND_TRIP.

As individuals migrate, there are three ways to categorize nodes:

  • Home: the node where the individuals reside; each individual has a single home node.

  • Origin: the “starting point” node for each leg of the migration. The origin updates as individuals move between nodes.

  • Destination: the node the individual is traveling to. The destination updates as individuals move between nodes.

For example, Individual 1 has a home node of Node A. They migrate from Node A to Node B. Node A is both the home node and the origin node, and Node B is the destination node. If Individual 1 migrates from Node B to Node C, Node A remains the home node, but now Node B is the origin node, and Node C is the destination node. If Individual 1 migrates from Node C back to Node A, Node C is the origin node, and Node A becomes the destination node and still remains the home node.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Duration_At_Node_Constant

float

0

3.40282E+38

-1

The duration at the destination node to use for all individuals, in days, when Duration_At_Node_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Constant": 8
}

Duration_At_Node_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the duration of time an individual or family spends at a destination node after intervention-based migration. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Duration_At_Node_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Duration_At_Node_Max and Duration_At_Node_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Duration_At_Node_Gaussian_Mean and Duration_At_Node_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Duration_At_Node_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Duration_At_Node_Kappa and Duration_At_Node_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Duration_At_Node_Log_Normal_Mu and Duration_At_Node_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Duration_At_Node_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Duration_At_Node_Proportion_0 and Peak_2_Value. This distribution does not use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Duration_At_Node_Mean_1, Duration_At_Node_Mean_2, and Duration_At_Node_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Exponential

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Exponential": 4.25
}

Duration_At_Node_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_At_Node_Gaussian_Mean": 8,
    "Duration_At_Node_Gaussian_Std_Dev": 1.5
}

Duration_At_Node_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

-1

The standard deviation of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_At_Node_Gaussian_Mean": 8,
    "Duration_At_Node_Gaussian_Std_Dev": 1.5
}

Duration_At_Node_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_At_Node_Kappa": 0.9,
    "Duration_At_Node_Lambda": 1.5
}

Duration_At_Node_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_At_Node_Log_Normal_Mu": 9,
    "Duration_At_Node_Log_Normal_Sigma": 2
}

Duration_At_Node_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_At_Node_Log_Normal_Mu": 9,
    "Duration_At_Node_Log_Normal_Sigma": 2
}

Duration_At_Node_Max

float

0

3.40282E+38

-1

The maximum duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_At_Node_Min": 2,
    "Duration_At_Node_Max": 7
}

Duration_At_Node_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_At_Node_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_At_Node_Min

float

0

3.40282E+38

-1

The minimum duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_At_Node_Min": 2,
    "Duration_At_Node_Max": 7
}

Duration_At_Node_Peak_2_Value

float

0

3.40282E+38

-1

The duration at the destination node value, in days, to assign to the remaining individuals when Duration_At_Node_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Proportion_0": 0.25,
    "Duration_At_Node_Peak_2_Value": 5
}

Duration_At_Node_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the duration at the destination node after migration, in days, when Duration_At_Node_Distribution is set to POISSON_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "POISSON_DISTRIBUTION",
    "Duration_At_Node_Poisson_Mean": 5
}

Duration_At_Node_Proportion_0

float

0

1

-1

The proportion of individuals to assign a value of zero days at the destination node when Duration_At_Node_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_At_Node_Proportion_0": 0.25,
    "Duration_At_Node_Peak_2_Value": 5
}

Duration_At_Node_Proportion_1

float

0

1

-1

The proportion of individuals in the first exponential distribution when Duration_At_Node_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_At_Node_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_At_Node_Mean_1": 4,
    "Duration_At_Node_Mean_2": 12,
    "Duration_At_Node_Proportion_1": 0.2
}

Duration_Before_Leaving_Constant

float

0

3.40282E+38

-1

The duration before leaving the origin node to use for every individual, in days, when Duration_Before_Leaving_Distribution is set to CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Constant": 8
}

Duration_Before_Leaving_Distribution

enum

NA

NA

NOT_INITIALIZED

The distribution type to use for assigning the duration of time an individual or family waits before migrating to the destination node after intervention-based migration. Each assigned value is a random draw from the distribution.

Possible values are:

NOT_INITIALIZED

No distribution set.

CONSTANT_DISTRIBUTION

Use the same value for each individual. Set Duration_Before_Leaving_Constant.

UNIFORM_DISTRIBUTION

Use a uniform distribution with a given minimum and maximum. Set Duration_Before_Leaving_Max and Duration_Before_Leaving_Min.

GAUSSIAN_DISTRIBUTION

The distribution is Gaussian (or normal). Values are resampled to ensure >= 0. Set Duration_Before_Leaving_Gaussian_Mean and Duration_Before_Leaving_Gaussian_Std_Dev.

EXPONENTIAL_DISTRIBUTION

The distribution is exponential with a given mean. Set Duration_Before_Leaving_Exponential.

WEIBULL_DISTRIBUTION

Use a Weibull distribution with a given shape and scale. Set Duration_Before_Leaving_Kappa and Duration_Before_Leaving_Lambda.

LOG_NORMAL_DISTRIBUTION

Use a log-normal distribution with a given mean and standard deviation of the natural log. Set Duration_Before_Leaving_Log_Normal_Mu and Duration_Before_Leaving_Log_Normal_Sigma.

POISSON_DISTRIBUTION

Use a Poisson distribution with a given mean. Set Duration_Before_Leaving_Poisson_Mean.

DUAL_CONSTANT_DISTRIBUTION

Use a distribution where some individuals are set to a value of zero and the rest to a given value. Set Duration_Before_Leaving_Proportion_0 and Peak_2_Value. This distribution does use the parameters set for CONSTANT_DISTRIBUTION.

DUAL_EXPONENTIAL_DISTRIBUTION

Use two exponential distributions with given means. Set Duration_Before_Leaving_Mean_1, Duration_Before_Leaving_Mean_2, and Duration_Before_Leaving_Proportion_1. This distribution does not use the parameters set for EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Exponential

float

0

3.40282E+38

-1

The mean of the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Exponential": 4.25
}

Duration_Before_Leaving_Gaussian_Mean

float

0

3.40282E+38

-1

The mean of the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_Before_Leaving_Gaussian_Mean": 8,
    "Duration_Before_Leaving_Gaussian_Std_Dev": 1.5
}

Duration_Before_Leaving_Gaussian_Std_Dev

float

1.17549E-38

3.40282E+38

1

The standard deviation of the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to GAUSSIAN_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "GAUSSIAN_DISTRIBUTION",
    "Duration_Before_Leaving_Gaussian_Mean": 8,
    "Duration_Before_Leaving_Gaussian_Std_Dev": 1.5
}

Duration_Before_Leaving_Kappa

float

1.17549E-38

3.40282E+38

-1

The shape value for the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_Before_Leaving_Kappa": 0.9,
    "Duration_Before_Leaving_Lambda": 1.5
}

Duration_Before_Leaving_Lambda

float

1.17549E-38

3.40282E+38

-1

The scale value for the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to WEIBULL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "WEIBULL_DISTRIBUTION",
    "Duration_Before_Leaving_Kappa": 0.9,
    "Duration_Before_Leaving_Lambda": 1.5
}

Duration_Before_Leaving_Log_Normal_Mu

float

-3.40282e+38

1.70141e+38

3.40282E+38

The mean of the natural log of the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_Before_Leaving_Log_Normal_Mu": 9,
    "Duration_Before_Leaving_Log_Normal_Sigma": 2
}

Duration_Before_Leaving_Log_Normal_Sigma

float

-3.40282e+38

1.70141e+38

3.40282E+38

The standard deviation of the natural log of the duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to LOG_NORMAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "LOG_NORMAL_DISTRIBUTION",
    "Duration_Before_Leaving_Log_Normal_Mu": 9,
    "Duration_Before_Leaving_Log_Normal_Sigma": 2
}

Duration_Before_Leaving_Max

float

0

3.40282E+38

-1

The maximum duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Mean_1

float

1.17549E-38

3.40282E+38

-1

The mean of the first exponential distribution, in days, when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Duration_Before_Leaving_Mean_2

float

1.17549E-38

3.40282E+38

-1

The mean of the second exponential distribution, in days, when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Duration_Before_Leaving_Min

float

0

3.40282E+38

-1

The minimum duration before leaving the origin node, in days, when Duration_Before_Leaving_Distribution is set to UNIFORM_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "UNIFORM_DISTRIBUTION",
    "Duration_Before_Leaving_Min": 2,
    "Duration_Before_Leaving_Max": 7
}

Duration_Before_Leaving_Peak_2_Value

float

0

3.40282E+38

-1

The duration before leaving the origin node, in days, to assign to the remaining individuals when Duration_Before_Leaving_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Proportion_0": 0.25,
    "Duration_Before_Leaving_Peak_2_Value": 5
}

Duration_Before_Leaving_Poisson_Mean

float

0

3.40282E+38

-1

The mean of the duration before leaving the origin node, in days, when Duration_Before_Leaving is set to POISSON_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "POISSON_DISTRIBUTION",
    "Duration_Before_Leaving_Poisson_Mean": 5
}

Duration_Before_Leaving_Proportion_0

float

0

1

-1

The proportion of individuals to assign a value of zero days before leaving the origin node when Duration_Before_Leaving_Distribution is set to DUAL_CONSTANT_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_CONSTANT_DISTRIBUTION",
    "Duration_Before_Leaving_Proportion_0": 0.25,
    "Duration_Before_Leaving_Peak_2_Value": 5
}

Duration_Before_Leaving_Proportion_1

float

0

1

-1

The proportion of individuals in the first exponential distribution when Duration_Before_Leaving_Distribution is set to DUAL_EXPONENTIAL_DISTRIBUTION.

 
{
    "Duration_Before_Leaving_Distribution": "DUAL_EXPONENTIAL_DISTRIBUTION",
    "Duration_Before_Leaving_Mean_1": 4,
    "Duration_Before_Leaving_Mean_2": 12,
    "Duration_Before_Leaving_Proportion_1": 0.2
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MigrateIndividuals",
        "Intervention_Name": "Seasonal migration for agriculture"
    }
}

Is_Moving

boolean

NA

NA

0

Set to true (1) to indicate the individual is permanently moving to a new home node for intervention-based migration. Once at the new home node, the person will be available for new round trips.

 
{
    "Is_Moving": 1
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

NodeID_To_Migrate_To

integer

0

4.29E+09

0

The destination node ID for intervention-based migration.

 
{
    "NodeID_To_Migrate_To": 26
}

{
  "Use_Defaults": 1,
  "Events": [
    {
      "class": "CampaignEvent",
      "Start_Day": 5,
      "Nodeset_Config": {
        "class": "NodeSetNodeList",
        "Node_List": [
          1
        ]
      },
      "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Residents_Only": 1,
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 1.0,
        "Intervention_Config": {
          "class": "MigrateIndividuals",
          "NodeID_To_Migrate_To": 2,
          "Duration_Before_Leaving_Distribution": "CONSTANT_DISTRIBUTION",
          "Duration_At_Node_Distribution": "CONSTANT_DISTRIBUTION",
          "Is_Moving": 0,
          "Duration_Before_Leaving_Constant": 0,
          "Duration_At_Node_Constant": 999
        }
      }
    }
  ]
}
ModifyStiCoInfectionStatus

The ModifyStiCoInfectionStatus intervention class creates or removes STI co-infections (which influence the rate of HIV transmission). This intervention can be used to represent things like STI treatment programs or STI outbreaks.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

New_STI_CoInfection_Status

boolean

0

1

0

Determines whether to apply STI co-infection, or cure/remove STI co-infection. Set to true (1) to include co-infection; set to false (0) to remove co-infection.

 
{
    "Intervention_Config": {
        "class": "ModifyStiCoInfectionStatus",
        "New_STI_CoInfection_Status": 1
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "HIV Outbreak via Prevalence Increase",
    "Events": [
        {
            "Description": "Initial STI outbreak",
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1.00,
                "Target_Demographic": "ExplicitAgeRanges",
                "Target_Age_Min": 15,
                "Target_Age_Max": 30,
                "Intervention_Config": {
                    "class": "ModifyStiCoInfectionStatus",
                    "New_STI_CoInfection_Status": 1
                }
            }
        },
        {
            "Description": "STI Diagnostic",
            "class": "CampaignEvent",
            "Start_Day": 31,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1.0,
                "Target_Demographic": "ExplicitAgeRanges",
                "Target_Age_Min": 15,
                "Target_Age_Max": 30.1,
                "Intervention_Config": {
                    "class": "StiCoInfectionDiagnostic",
                    "Treatment_Fraction": 1.0,
                    "Event_Or_Config": "Config",
                    "Positive_Diagnosis_Config":
                    {
                        "class": "ModifyStiCoInfectionStatus",
                        "New_STI_CoInfection_Status": 0
                    }
                }
            }
        }
    ]
}
MultiEffectBoosterVaccine

The MultiEffectBoosterVaccine intervention class is derived from MultiEffectVaccine and preserves many of the same parameters. Upon distribution and successful take, the vaccine’s effect in each immunity compartment (acquisition, transmission, and mortality) is determined by the recipient’s immune state. If the recipient’s immunity modifier in the corresponding compartment is above a user-specified threshold, then the vaccine’s initial effect will be equal to the corresponding priming parameter. If the recipient’s immune modifier is below this threshold, then the vaccine’s initial effect will be equal to the corresponding boost parameter. After distribution, the effect wanes, just like a MultiEffectVaccine. The behavior is intended to mimic biological priming and boosting.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acquire_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine acquisition. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Acquire_Config": {
        "Initial_Effect": 0.9,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Boost_Acquire

float

0

1

0

Specifies the boosting effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Acquire": 0.7
}

Boost_Mortality

float

0

1

0

Specifies the boosting effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Mortality": 1.0
}

Boost_Threshold_Acquire

float

0

1

0

Specifies how much acquisition immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Acquire": 0.0
}

Boost_Threshold_Mortality

float

0

1

0

Specifies how much mortality immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Mortality": 0.0
}

Boost_Threshold_Transmit

float

0

1

0

Specifies how much transmission immunity is required before the vaccine changes from a prime to a boost.

 
{
    "Boost_Threshold_Transmit": 0.0
}

Boost_Transmit

float

0

1

0

Specifies the boosting effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine. This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Boost_Transmit": 0.5
}

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

MultiEffectBoosterVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiEffectBoosterVaccine",
        "Intervention_Name": "Tetanus booster shot"
    }
}

Mortality_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine mortality. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Mortality_Config": {
        "Initial_Effect": 1.0,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prime_Acquire

float

0

1

0

Specifies the priming effect on acquisition immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Acquire": 0.1
}

Prime_Mortality

float

0

1

0

Specifies the priming effect on mortality immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Mortality": 0.3
}

Prime_Transmit

float

0

1

0

Specifies the priming effect on transmission immunity for naive individuals (without natural or vaccine-derived immunity) for a multi-effect booster vaccine.

 
{
    "Prime_Transmit": 0.2
}

Transmit_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine transmission. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Transmit_Config": {
        "Initial_Effect": 0.6,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "Generic Seattle Regression Campaign",
    "Events": [{
        "Event_Coordinator_Config": {
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "Cost_To_Consumer": 10.0,
                "Vaccine_Take": 1,
                "Prime_Acquire": 0.1,
                "Prime_Transmit": 0.2,
                "Prime_Mortality": 0.3,
                "Boost_Acquire": 0.7,
                "Boost_Transmit": 0.5,
                "Boost_Mortality": 1.0,
                "Boost_Threshold_Acquire": 0.0,
                "Boost_Threshold_Transmit": 0.0,
                "Boost_Threshold_Mortality": 0.0,
                "Acquire_Config": {
                    "Box_Duration": 100,
                    "Initial_Effect": 0.5,
                    "class": "WaningEffectBox"
                },
                "Transmit_Config": {
                    "Box_Duration": 100,
                    "Initial_Effect": 0.5,
                    "class": "WaningEffectBox"
                },
                "Mortality_Config": {
                    "Box_Duration": 100,
                    "Initial_Effect": 0.5,
                    "class": "WaningEffectBox"
                },
                "class": "MultiEffectBoosterVaccine"
            },
            "Target_Demographic": "Everyone",
            "class": "StandardInterventionDistributionEventCoordinator"
        },
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 1,
        "class": "CampaignEvent"
    }]
}
MultiEffectVaccine

The MultiEffectVaccine intervention class implements vaccine campaigns in the simulation. Vaccines can effect all of the following:

  • Reduce the likelihood of acquiring an infection

  • Reduce the likelihood of transmitting an infection

  • Reduce the likelihood of death

After distribution, the effect wanes over time.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Acquire_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine acquisition. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Acquire_Config": {
        "Initial_Effect": 0.9,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

MultiEffectVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiEffectVaccine",
        "Intervention_Name": "Routine MMR vaccination"
    }
}

Mortality_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine mortality. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Mortality_Config": {
        "Initial_Effect": 1.0,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Transmit_Config

JSON object

NA

NA

NA

The configuration for multi-effect vaccine transmission. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Transmit_Config": {
        "Initial_Effect": 0.6,
        "Decay_Time_Constant": 2525,
        "class": "WaningEffectExponential"
    }
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

{
    "Events": [{
        "Event_Coordinator_Config": {
            "Demographic_Coverage": 1,
            "Intervention_Config": {
                "Cost_To_Consumer": 20,
                "Vaccine_Take": 1,
                "Vaccine_Type": "Generic",
                "class": "MultiEffectVaccine",
                "Acquire_Config": {
                    "Initial_Effect": 0.9,
                    "Decay_Time_Constant": 7300,
                    "class": "WaningEffectExponential"
                },
                "Transmit_Config": {
                    "Initial_Effect": 0.9,
                    "Decay_Time_Constant": 7300,
                    "class": "WaningEffectExponential"
                },
                "Mortality_Config": {
                    "Initial_Effect": 1.0,
                    "Decay_Time_Constant": 7300,
                    "class": "WaningEffectExponential"
                }
            },
            "Property_Restrictions": [
                "Accessibility:VaccineTake"
            ],
            "Target_Age_Max": 100,
            "Target_Age_Min": 12,
            "Target_Demographic": "ExplicitAgeRanges",
            "class": "StandardInterventionDistributionEventCoordinator"
        },
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 1,
        "class": "CampaignEvent"
    }],
    "Use_Defaults": 1
}
MultiInterventionDistributor

The MultiInterventionDistributor intervention class allows you to input a list of interventions, rather than just a single intervention, to be distributed simultaneously to the same individuals.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_List

array of JSON objects

NA

NA

NA

The list of individual interventions that is distributed by MultiInterventionDistributor.

 
{
    "Actual_IndividualIntervention_Config": {
        "Intervention_List": [
            {
                "Cost_To_Consumer": 1,
                "Dosing_Type": "FullTreatmentNewDetectionTech",
                "Drug_Type": "Artemether",
                "class": "AntimalarialDrug"
            },
            {
                "Cost_To_Consumer": 1,
                "Dosing_Type": "FullTreatmentNewDetectionTech",
                "Drug_Type": "Lumefantrine",
                "class": "AntimalarialDrug"
            }
        ],
        "class": "MultiInterventionDistributor"
    }
}

Intervention_Name

string

NA

NA

MultiInterventionDistributor

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "MultiInterventionDistributor",
        "Intervention_Name": "Complete malaria campaign"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Events": [{
        "class": "SimpleDiagnostic",
        "Treatment_Fraction": 0.7,
        "Base_Sensitivity": 0.8,
        "Base_Specificity": 0.9,
        "Cost_To_Consumer": 0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Config",
        "Positive_Diagnosis_Config": {
            "class": "MultiInterventionDistributor",
            "Intervention_List": [{
                    "class": "SimpleVaccine",
                    "Vaccine_Type": "AcquisitionBlocking",
                    "Vaccine_Take": 1,
                    "Waning_Config": {
                        "class": "WaningEffectBox",
                        "Box_Duration": 3650,
                        "Initial_Effect": 0.1
                    }
                },
                {
                    "class": "SimpleVaccine",
                    "Vaccine_Type": "TransmissionBlocking",
                    "Vaccine_Take": 1,
                    "Waning_Config": {
                        "class": "WaningEffectBox",
                        "Box_Duration": 3650,
                        "Initial_Effect": 0.9
                    }
                },
                {
                    "class": "SimpleVaccine",
                    "Vaccine_Type": "MortalityBlocking",
                    "Vaccine_Take": 1,
                    "Waning_Config": {
                        "class": "WaningEffectBox",
                        "Box_Duration": 3650,
                        "Initial_Effect": 0.5
                    }
                }
            ]
        }
    }]
}
OutbreakIndividual

The OutbreakIndividual intervention class introduces contagious diseases that are compatible with the simulation type to existing individuals using the individual targeted features configured in the appropriate event coordinator. To instead add new infection individuals, use Outbreak.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Clade

integer

0

10

0

The clade ID of the outbreak infection. Together with the genome ID (Genome) they are a unitary object representing a strain of infection, which allows for differentiation among infections. Values for Clade may range from 0 to Number_of_Clades-1 (set in the configuration file).

 
{
    "Clade": 1
}

Genome

integer

-1

1.67E+07

0

The genome ID of the outbreak infection. Together with the clade ID (Clade) they represent an infection as a unitary object. Values for Genome may range from -1 to 2Log2_Number_of_Genomes_per_Clade-1. Set this to -1 to create a random number generator.

Intervention distribution example:

{
    "Enable_Strain_Tracking": 1,
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 0.001,
                "Intervention_Config": {
                    "Clade": 1,
                    "Genome": 3,
                    "IgnoreImmunity": 1,
                    "class": "Outbreak"
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Event_Name": "Outbreak",
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 30,
            "class": "CampaignEvent"
        }
    ]
}

Ignore_Immunity

boolean

NA

NA

1

Individuals will be force-infected (with a specific strain) regardless of actual immunity level when set to true (1).

 
{
    "Intervention_Config": {
        "Clade": 0,
        "Genome": 0,
        "class": "OutbreakIndividual",
        "Ignore_Immunity": 0
    }
}

Incubation_Period_Override

integer

-1

2147480000.0

-1

The incubation period, in days, that infected individuals will go through before becoming infectious. This value overrides the incubation period set in the configuration file. Set to -1 to honor the configuration parameter settings.

 
{
    "Incubation_Period_Override": 0
}

{
  "Events": [
    {
      "Event_Coordinator_Config": {
        "Demographic_Coverage": 0.001,
        "Intervention_Config": {
          "Clade": 1,
          "Genome": 3,
          "IgnoreImmunity": 1,
          "class": "OutbreakIndividual"
        },
        "Target_Demographic": "Everyone",
        "class": "StandardInterventionDistributionEventCoordinator"
      },
      "Nodeset_Config": {
        "class": "NodeSetAll"
      },
      "Start_Day": 30,
      "class": "CampaignEvent"
    }
  ]
}
PMTCT

The PMTCT (Prevention of Mother-to-Child Transmission) intervention class is used to define the efficacy of PMTCT treatment at time of birth. This can only be used for mothers who are not on suppressive ART and will automatically expire 40 weeks after distribution. Efficacy will be reset to 0 once it expires.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Efficacy

float

0

1

0.5

Represents the efficacy of a Prevention of Mother to Child Transmission (PMTCT) intervention, defined as the rate ratio of mother to child transmission (MTCT) between women receiving the intervention and women not receiving the intervention. A setting of 1 is equivalent to 100% blocking efficacy, and 0 reverts to the default probability of transmission, configured through the config.json parameter Maternal_Transmission_Probability.

 
{
    "Actual_IndividualIntervention_Config": {
        "class": "PMTCT",
        "Efficacy": 0.5
    }
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "PMTCT",
        "Intervention_Name": "Pregnant mothers on preventative"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "DrawBlood validation",
    "Events": [
        {
            "Event_Name": "Nevarapine",
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 1,
                "Intervention_Config": {
                    "Actual_IndividualIntervention_Config": {
                        "class": "PMTCT",
                        "Efficacy": 0.5
                    },
                    "Trigger_Condition_List": [
                        "FourteenWeeksPregnant"
                    ],
                    "Duration": 365,
                    "class": "NodeLevelHealthTriggeredIV"
                },
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Day": 1,
            "class": "CampaignEvent"
        }
    ]
}
PropertyValueChanger

The PropertyValueChanger intervention class assigns new individual property values to individuals. You must update one property value and have the option to update another using New_Property_Value. This parameter is generally used to move patients from one intervention state in the health care cascade (InterventionStatus) to another, though it can be used for any individual property. Individual property values are user-defined in the demographics file (see NodeProperties and IndividualProperties for more information). Note that the HINT feature does not need to be enabled to use this intervention. To instead change node properties, use NodePropertyValueChanger.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Daily_Probability

float

0

1

1

The daily probability that an individual will move to the Target_Property_Value.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to nodes with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Intervention_Name

string

NA

NA

PropertyValueChanger

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Intervention_Name": "Diagnosed HIV+ to ART"
    }
}

Maximum_Duration

float

-1

3.40E+38

3.40E+38

The maximum amount of time individuals have to move to a new group. This timing works in conjunction with Daily_Probability.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Revert

float

0

3.40E+38

0

The number of days before an individual moves back to their original group.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Target_Property_Key

string

NA

NA

“

The name of the individual property type whose value will be updated by the intervention.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "New_Property_Value": "",
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

Target_Property_Value

string

NA

NA

“

The user-defined value of the individual property that will be assigned to the individual.

 
{
    "Intervention_Config": {
        "class": "PropertyValueChanger",
        "Disqualifying_Properties": [],
        "Target_Property_Key": "Risk",
        "Target_Property_Value": "LOW",
        "New_Property_Value": "",
        "Daily_Probability": 1.0,
        "Maximum_Duration": 0,
        "Revert": 0
    }
}

{
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 10,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Property_Restrictions": [
                    "Risk:LOW"
                ],
                "Intervention_Config": {
                    "class": "PropertyValueChanger",
                    "Disqualifying_Properties": [ "InterventionStatus:Diagnosed"],
                    "New_Property_Value": "InterventionStatus:Monitor",
                    "Target_Property_Key" : "Risk",
                    "Target_Property_Value" : "HIGH",
                    "Daily_Probability" : 1.0,
                    "Maximum_Duration" : 0,
                    "Revert" : 10
                }
            }
        }
    ],
    "Use_Defaults": 1
}
SimpleBoosterVaccine

The SimpleBoosterVaccine intervention class is derived from SimpleVaccine and preserves many of the same parameters. The behavior is much like SimpleVaccine, except that upon distribution and successful take, the vaccine’s effect is determined by the recipient’s immune state. If the recipient’s immunity modifier in the corresponding channel (acquisition, transmission, or mortality) is above a user-specified threshold, then the vaccine’s initial effect will be equal to the corresponding priming parameter. If the recipient’s immune modifier is below this threshold, then the vaccine’s initial effect will be equal to the corresponding boosting parameter. After distribution, the effect wanes, just like SimpleVaccine. In essence, this intervention provides a SimpleVaccine intervention with one effect to all naive (below- threshold) individuals, and another effect to all primed (above-threshold) individuals; this behavior is intended to mimic biological priming and boosting.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Boost_Effect

float

0

1

1

Specifies the boosting effect on [acquisition/transmission/mortality] immunity for previously exposed individuals (either natural or vaccine-derived). This does not replace current immunity, it builds multiplicatively on top of it.

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Boost_Threshold

float

0

1

0

Specifies how much immunity is required before the vaccine changes from a priming effect to a boosting effect.

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Efficacy_Is_Multiplicative

boolean

NA

NA

1

The overall vaccine efficacy when individuals receive more than one vaccine. When set to true (1), the vaccine efficacies are multiplied together; when set to false (0), the efficacies are additive.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Intervention_Name

string

NA

NA

SimpleBoosterVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "SimpleBoosterVaccine",
        "Intervention_Name": "Tetanus booster shot"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Prime_Effect

float

0

1

1

Specifies the priming effect on [acquisition/transmission/mortality] immunity for naive individuals (without natural or vaccine-derived immunity).

 
{
    "Intervention_Config": {
        "Cost_To_Consumer": 10.0,
        "Vaccine_Take": 1,
        "Vaccine_Type": "MortalityBlocking",
        "Prime_Effect": 0.25,
        "Boost_Effect": 0.45,
        "Boost_Threshold": 0.0,
        "Waning_Config": {
            "Box_Duration": 10,
            "Initial_Effect": 1,
            "class": "WaningEffectBox"
        },
        "class": "SimpleBoosterVaccine"
    }
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Vaccine_Type

enum

NA

NA

Generic

The type of vaccine to distribute in a vaccine intervention. Possible values are:

Generic

The vaccine can reduce transmission, acquisition, and mortality.

TransmissionBlocking

The vaccine will reduce pathogen transmission.

AcquisitionBlocking

The vaccine will reduce the acquisition of the pathogen by reducing the force of infection experienced by the vaccinated individual.

MortalityBlocking

The vaccine reduces the disease-mortality rate of a vaccinated individual.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Waning_Config

JSON object

NA

NA

NA

The configuration of how the intervention efficacy wanes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Waning_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 1,
        "class": "WaningEffectBox"
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "Generic Seattle Regression Campaign",
    "Events": [{
        "class": "CampaignEvent",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 20,
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 1.0,
            "Intervention_Config": {
                "class": "SimpleBoosterVaccine",
                "Cost_To_Consumer": 10.0,
                "Vaccine_Take": 1,
                "Vaccine_Type": "MortalityBlocking",
                "Prime_Effect": 0.25,
                "Boost_Effect": 0.45,
                "Boost_Threshold": 0.0,
                "Waning_Config": {
                    "Box_Duration": 10,
                    "Initial_Effect": 1,
                    "class": "WaningEffectBox"
                }
            }
        }
    }]
}
SimpleDiagnostic

The SimpleDiagnostic intervention class identifies infected individuals, regardless of disease state, based on specified diagnostic sensitivity and specificity. Diagnostics are a key component of modern disease control efforts, whether used to identify high-risk individuals, infected individuals, or drug resistance. This intervention class distributes a specified intervention to a fraction of individuals who test positive.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40E+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40E+38

0

Diagnosis occurs when the intervention is distributed; this parameter governs the time (in days) from positive diagnosis to action on that diagnosis.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

NA

NA

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

SimpleDiagnostic

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Name": "Diagnostic_Sample"
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

NA

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Events":[{
            "class":"CampaignEvent",
            "Start_Day":200,
            "Nodeset_Config":{
                "class":"NodeSetAll"
            },
            "Event_Coordinator_Config":{
                "class":"StandardInterventionDistributionEventCoordinator",
                "Target_Demographic":"Everyone",
                "Demographic_Coverage": 1.0,
                "Intervention_Config":{
                    "class":"SimpleDiagnostic",
                    "Base_Sensitivity":1.0,
                    "Base_Specificity":1.0,
                    "Cost_To_Consumer":0,
                    "Days_To_Diagnosis":5.0,
                    "Dont_Allow_Duplicates":0,
                    "Event_Or_Config":"Event",
                    "Positive_Diagnosis_Event":"Acorn",
                    "Intervention_Name":"Diagnostic_Sample",
                    "Treatment_Fraction":1.0
                }
            }
        }],
    "Use_Defaults":1
}
SimpleHealthSeekingBehavior

The SimpleHealthSeekingBehavior intervention class models the time delay that typically occurs between when an individual experiences onset of symptoms and when they seek help from a health care provider. Several factors may contribute to such delays including accessibility, cost, and trust in the health care system. This intervention models this time delay as an exponential process; at every time step, the model draws randomly to determine if the individual will receive the specified intervention. As an example, this intervention can be nested in a NodeLevelHealthTriggeredIV so that when an individual is infected, he or she receives a SimpleHealthSeekingBehavior, representing that the individual will now seek care. The individual subsequently seeks care with an exponentially distributed delay and ultimately receives the specified intervention.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Actual_IndividualIntervention_Config

JSON object

NA

NA

NA

The configuration of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class.

 
{
    "Actual_IndividualIntervention_Config": {
        "Cost_To_Consumer": 1,
        "Drug_Type": "FirstLineCombo",
        "Durability_Profile": "FIXED_DURATION_CONSTANT_EFFECT",
        "Primary_Decay_Time_Constant": 180,
        "Remaining_Doses": 1,
        "Secondary_Decay_Time_Constant": 0,
        "TB_Drug_Cure_Rate": 0.2,
        "TB_Drug_Inactivation_Rate": 1e-09,
        "class": "AntiTBDrug"
    }
}

Actual_IndividualIntervention_Event

enum

NA

NA

NA

The event of an actual intervention sought. Selects a class for the intervention and configures the parameters specific for that intervention class. See Event list for possible values.

 
{
    "Actual_IndividualIntervention_Config": {
        "Actual_IndividualIntervention_Event": "ProviderOrdersTBTest",
        "Tendency": 0.005,
        "Event_Or_Config": "Event",
        "class": "SimpleHealthSeekingBehavior"
    }
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

SimpleHealthSeekingBehavior

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "SimpleHealthSeekingBehavior",
        "Intervention_Name": "Return to clinic after treatment is unsuccessful"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Single_Use

boolean

NA

NA

1

If set to true (1), the health-seeking behavior gets used once and discarded. If set to false (0), it remains indefinitely.

 
{
    "Single_Use": 1
}

Tendency

float

0

1

1

The probability of seeking healthcare.

 
{
    "Tendency": 0.01
}

{
     "Use_Defaults": 1,
     "Events": [{
          "class": "CampaignEvent",
          "Event_Name": "Drugs after TB activation",
          "Nodeset_Config": {
               "class": "NodeSetAll"
          },
          "Start_Day": 9125,
          "Event_Coordinator_Config": {
               "class": "StandardInterventionDistributionEventCoordinator",
               "Number_Repetitions": 1,
               "Target_Demographic": "Everyone",
               "Demographic_Coverage": 1,
               "Intervention_Config": {
                    "class": "NodeLevelHealthTriggeredIV",
                    "Trigger_Condition_List": ["NewInfectionEvent"],
                    "Actual_IndividualIntervention_Config": {
                         "class": "SimpleHealthSeekingBehavior",
                         "Event_Or_Config": "Config",
                         "Tendency": 0.0015,
                         "Actual_IndividualIntervention_Config": {
                              "class": "AntiTBDrug",
                              "Cost_To_Consumer": 90,
                              "Drug_Type": "FirstLineCombo",
                              "Durability_Profile": "FIXED_DURATION_CONSTANT_EFFECT",
                              "Primary_Decay_Time_Constant": 180,
                              "Remaining_Doses": 1,
                              "Secondary_Decay_Time_Constant": 0
                         }
                    }
               }
          }
     }]
}
SimpleVaccine

The SimpleVaccine intervention class implements vaccine campaigns in the simulation. Vaccines can have an effect on one of the following:

  • Reduce the likelihood of acquiring an infection

  • Reduce the likelihood of transmitting an infection

  • Reduce the likelihood of death

To configure vaccines that have an effect on more than one of these, use MultiEffectVaccine instead.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

999999

10

The unit cost per vaccine (unamortized).

 
{
    "Cost_To_Consumer": 10.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

NA

NA

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Efficacy_Is_Multiplicative

boolean

NA

NA

1

The overall vaccine efficacy when individuals receive more than one vaccine. When set to true (1), the vaccine efficacies are multiplied together; when set to false (0), the efficacies are additive.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Intervention_Name

string

NA

NA

SimpleVaccine

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Intervention_Name": "Routine MMR vaccination"
    }
}

New_Property_Value

string

NA

NA

NA

An optional IndividualProperty key:value pair that will be assigned when the intervention is first updated. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Vaccine_Take

float

0

1

1

The rate at which delivered vaccines will successfully stimulate an immune response and achieve the desired efficacy. For example, if it is set to 0.9, there will be a 90 percent chance that the vaccine will start with the specified efficacy, and a 10 percent chance that it will have no efficacy at all.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Vaccine_Type

enum

NA

NA

Generic

The type of vaccine to distribute in a vaccine intervention. Possible values are:

Generic

The vaccine can reduce transmission, acquisition, and mortality.

TransmissionBlocking

The vaccine will reduce pathogen transmission.

AcquisitionBlocking

The vaccine will reduce the acquisition of the pathogen by reducing the force of infection experienced by the vaccinated individual.

MortalityBlocking

The vaccine reduces the disease-mortality rate of a vaccinated individual.

 
{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 10,
        "Vaccine_Type": "AcquisitionBlocking",
        "Vaccine_Take": 1,
        "Efficacy_Is_Multiplicative": 0,
        "Waning_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 0.3
        }
    }
}

Waning_Config

JSON object

NA

NA

NA

The configuration of how the intervention efficacy wanes over time. Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Waning_Config": {
        "Box_Duration": 3650,
        "Initial_Effect": 1,
        "class": "WaningEffectBox"
    }
}

{
    "Events": [{
        "class": "CampaignEvent",
        "Nodeset_Config": {
            "class": "NodeSetAll"
        },
        "Start_Day": 60,
        "Event_Coordinator_Config": {
            "class": "StandardInterventionDistributionEventCoordinator",
            "Target_Demographic": "Everyone",
            "Demographic_Coverage": 0.5,
            "Intervention_Config": {
                "class": "SimpleVaccine",
                "Cost_To_Consumer": 10.0,
                "Vaccine_Take": 1,
                "Vaccine_Type": "AcquisitionBlocking",
                "Waning_Config": {
                    "Box_Duration": 3650,
                    "Initial_Effect": 1,
                    "class": "WaningEffectBox"
                }
            }
        }
    }],
    "Use_Defaults": 1
}
STIBarrier

The STIBarrier intervention is used to reduce the probability of STI or HIV transmission by applying a time-variable probability of condom usage. Each STIBarrier intervention is directed at a specific relationship type, and must be configured as a sigmoid trend over time.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Cost_To_Consumer

float

0

999999

10

Determines the unit cost when using the STIBarrier intervention to change defaults from demographics. Note that there is no cost for condoms distributed using demographics-configured default usage probabilities.

 
{
    "Cost_To_Consumer": 1.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Early

float

0

1

1

The left asymptote for the sigmoid trend over time. The Early value must be smaller than the Late value.

 
{
    "Intervention_Config": {
        "class": "STIBarrier",
        "Early": 0.0,
        "Late": 1.0,
        "Midyear": 1990,
        "Rate": 0.0,
        "Relationship_Type": "TRANSITORY",
        "Cost_To_Consumer": 1.0
    }
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Name": "Diagnostic_Sample"
}

Late

float

0

1

1

The right asymptote for the sigmoid trend over time. The Late value must be larger than the Early value.

 
{
    "Intervention_Config": {
        "class": "STIBarrier",
        "Early": 0.0,
        "Late": 1.0,
        "Midyear": 1990,
        "Rate": 0.0,
        "Relationship_Type": "TRANSITORY",
        "Cost_To_Consumer": 1.0
    }
}

MidYear

float

0

1

1

The time of the inflection point in the sigmoid trend over time.

 
{
    "Intervention_Config": {
        "class": "STIBarrier",
        "Early": 0.0,
        "Late": 1.0,
        "Midyear": 1990,
        "Rate": 0.0,
        "Relationship_Type": "TRANSITORY",
        "Cost_To_Consumer": 1.0
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Rate

float

0

1

1

The slope of the inflection point in the sigmoid trend over time. A Rate of 1 sets the slope to a 25% change in probability per year. Specify a negative Rate (e.g. -1) to achieve a negative sigmoid.

 
{
    "Intervention_Config": {
        "class": "STIBarrier",
        "Early": 0.0,
        "Late": 1.0,
        "Midyear": 1990,
        "Rate": 0.0,
        "Relationship_Type": "TRANSITORY",
        "Cost_To_Consumer": 1.0
    }
}

Relationship_Type

enum

NA

NA

TRANSITORY

The relationship type to which the condom usage probability is applied. Possible values are:

  • TRANSITORY

  • INFORMAL

  • MARITAL

 
{
    "Intervention_Config": {
        "class": "STIBarrier",
        "Early": 0.0,
        "Late": 1.0,
        "Midyear": 1990,
        "Rate": 0.0,
        "Relationship_Type": "TRANSITORY",
        "Cost_To_Consumer": 1.0
    }
}

{
    "Campaign_Name": "Baseline campaign for HIV-5 examples",
    "Events": [
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "class": "STIBarrier",
                    "Early": 1.0,
                    "Late": 1.0,
                    "Midyear": 1990,
                    "Rate": 1.0,
                    "Relationship_Type": "INFORMAL",
                    "Cost_To_Consumer": 1.0
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Year": 1992,
            "class": "CampaignEventByYear"
        },
        {
            "Event_Coordinator_Config": {
                "Demographic_Coverage": 1.0,
                "Intervention_Config": {
                    "class": "STIBarrier",
                    "Early": 1.0,
                    "Late": 1.0,
                    "Midyear": 1990,
                    "Rate": 1.0,
                    "Relationship_Type": "MARITAL",
                    "Cost_To_Consumer": 1.0
                },
                "Target_Demographic": "Everyone",
                "class": "StandardInterventionDistributionEventCoordinator"
            },
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Start_Year": 1996,
            "class": "CampaignEventByYear"
        }
    ],
    "Use_Defaults": 1
}
StiCoInfectionDiagnostic

The StiCoInfectionDiagnostic intervention class is based on SimpleDiagnostic and allows for diagnosis of STI co-infection. It includes SimpleDiagnostic features and works in conjunction with the ModifyCoInfectionStatus flag.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "StiCoInfectionDiagnostic",
        "Intervention_Name": "Test for other STIs upon positive HIV diagnosis"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
    "Use_Defaults": 1,
    "Campaign_Name": "HIV Outbreak via Prevalence Increase",
    "Events": [
        {
            "Description": "STI Diagnostic",
            "class": "CampaignEvent",
            "Start_Day": 61,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1.00,
                "Target_Demographic": "ExplicitAgeRanges",
                "Target_Age_Min": 15,
                "Target_Age_Max": 31,
                "Intervention_Config": {
                    "class": "StiCoInfectionDiagnostic",
                    "Event_Or_Config": "Config",
                    "Treatment_Fraction": 1.0,
                    "Positive_Diagnosis_Config":
                    {
                        "class": "ModifyStiCoInfectionStatus",
                        "New_STI_CoInfection_Status": 0
                    }
                }
            }
        }
    ]
}
STIIsPostDebut

The STIIsPostDebut intervention class is based on SimpleDiagnostic, but adds a check to see if the individual is post-STI debut. Note that this is not connected to IndividualProperties in the demographics file.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

The table below describes all possible parameters with which this class can be configured. The JSON example that follows shows one potential configuration.

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Base_Sensitivity

float

0

1

1

The sensitivity of the diagnostic. This sets the proportion of the time that individuals with the condition being tested receive a positive diagnostic test. When set to 1, the diagnostic always accurately reflects the condition. When set to zero, then individuals who have the condition always receive a false-negative diagnostic test.

 
{
    "Base_Sensitivity": 0.8
}

Base_Specificity

float

0

1

1

The specificity of the diagnostic. This sets the proportion of the time that individuals without the condition being tested receive a negative diagnostic test. When set to 1, the diagnostic always accurately reflects the lack of having the condition. When set to zero, then individuals who do not have the condition always receive a false-positive diagnostic test.

 
{
    "Base_Specificity": 0.9
}

Cost_To_Consumer

float

0

3.40282e+38

1

The unit ‘cost’ assigned to the diagnostic. Setting Cost_To_Consumer to zero for all other interventions, and to a non-zero amount for one intervention, provides a convenient way to track the number of times the intervention has been applied in a simulation.

 
{
    "Cost_To_Consumer": 0.333
}

Days_To_Diagnosis

float

0

3.40282e+38

0

The number of days from test until positive diagnosis. A negative test result is given immediately when the intervention is distributed.

 
{
    "Days_To_Diagnosis": 0.0
}

Disqualifying_Properties

array of strings

NA

NA

[]

A list of IndividualProperty key:value pairs that cause an intervention to be aborted (persistent interventions will stop being distributed to individuals with these values). See NodeProperties and IndividualProperties parameters for more information. Generally used to control the flow of health care access. For example, to prevent the same individual from accessing health care via two different routes at the same time.

 
{
    "Disqualifying_Properties": [
        "InterventionStatus:LostForever"
    ]
}

Dont_Allow_Duplicates

boolean

0

1

0

If an individual’s container has an intervention, set to true (1) to prevent them from receiving another copy of the intervention. Supported by all intervention classes.

 
{
    "Dont_Allow_Duplicates": 0
}

Enable_Is_Symptomatic

boolean

0

1

0

If true (1), requires an infection to be symptomatic to return a positive test.

 
{
    "Enable_Is_Symptomatic": 1,
    "Base_Specificity": 0.85,
    "Base_Sensitivity": 0.92
}

Event_Or_Config

enum

NA

NA

Config

Specifies whether the current intervention (or a positive diagnosis, depending on the intervention class) distributes a nested intervention (the Config option) or an event will be broadcast which may trigger other interventions in the campaign file (the Event option). Possible values are:

  • Event

  • Config

 
{
    "Event_Or_Config": "Config"
}

Intervention_Name

string

NA

NA

NA

The optional name used to refer to this intervention as a means to differentiate it from others that use the same class.

 
{
    "Intervention_Config": {
        "class": "STIIsPostDebut",
        "Intervention_Name": "Diagnostic as part of routine HIV screening"
    }
}

Negative_Diagnosis_Event

enum

NA

NA

“”

The name of the event to broadcast when an individual is found to NOT be Post-Debut age. Event_or_Config must be set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "Event_Or_Config": "Event",
        "Negative_Diagnosis_Event": "PreDebut",
        "Positive_Diagnosis_Event": "PostDebut",
        "class": "STIIsPostDebut"
    }
}

New_Property_Value

string

NA

NA

“

An optional IndividualProperty key:value pair that will be assigned when the intervention is distributed. See NodeProperties and IndividualProperties parameters for more information. Generally used to indicate the broad category of health care cascade to which an intervention belongs to prevent individuals from accessing care through multiple pathways. For example, if an individual must already be taking a particular medication to be prescribed a new one.

 
{
    "New_Property_Value": "InterventionStatus:None"
}

Positive_Diagnosis_Config

JSON object

NA

NA

NA

The intervention distributed to individuals if they test positive. Only used when Event_Or_Config is set to Config.

 
{
    "Event_Or_Config": "Config",
    "Positive_Diagnosis_Config": {
        "class": "SimpleVaccine",
        "Cost_To_Consumer": 0.333,
        "Secondary_Decay_Time_Constant": 1,
        "Vaccine_Take": 1,
        "Vaccine_Type": "AcquisitionBlocking",
        "Waning_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0.1,
            "class": "WaningEffectBox"
        }
    }
}

Positive_Diagnosis_Event

enum

NA

NA

“”

If the test is positive, this specifies an event that can trigger another intervention when the event occurs. Only used if Event_Or_Config is set to Event. See Event list for possible values.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",        
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

Treatment_Fraction

float

0

1

1

The fraction of positive diagnoses that are treated or given the Positive_Diagnosis_Config or Positive_Diagnosis_Event when used in campaign classes that trigger separate interventions or events upon a positive diagnosis.

 
{
    "Intervention_Config": {
        "class": "SimpleDiagnostic",
        "Base_Sensitivity": 1.0,
        "Base_Specificity": 1.0,
        "Cost_To_Consumer": 0.0,
        "Days_To_Diagnosis": 0.0,
        "Event_Or_Config": "Event",
        "Positive_Diagnosis_Event": "TestedPositive_CureMeNow",
        "Treatment_Fraction": 1.0
    }
}

{
     "Use_Defaults": 1,
     "Campaign_Name": "IsPostDebutCensus",
     "Events": [
        {
            "class": "CampaignEvent",
            "Event_Name": "Is Post Debut?  Broadcast for event reporter.",
            "Start_Day": 14539,
            "Nodeset_Config": { "class": "NodeSetAll" },
            "Event_Coordinator_Config":
            {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Demographic_Coverage": 1,
                "Intervention_Config":
                {
                    "class": "STIIsPostDebut",
                    "Event_Or_Config": "Event",
                    "Positive_Diagnosis_Event": "PostDebut",
                    "Negative_Diagnosis_Event": "PreDebut"
                }
            }
        }
     ]
}
Waning effect classes

The following classes are nested within interventions (both individual-level and node-level) to indicate how their efficacy wanes over time. They can be used with several parameters including Blocking_Config, Killing_Config, and Waning_Config. Note that waning effect parameters do not control the overall duration of an intervention and are not assigned probabilistically.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

See the example below that uses a mix of different waning effect classes and the tables below that describe all parameters that can be used with each waning effect class.

{
    "Events": [
        {
            "class": "CampaignEvent",
            "Start_Day": 1,
            "Nodeset_Config": {
                "class": "NodeSetAll"
            },
            "Event_Coordinator_Config": {
                "class": "StandardInterventionDistributionEventCoordinator",
                "Target_Demographic": "Everyone",
                "Demographic_Coverage": 1.0,
                "Number_Repetitions": -1,
                "Timesteps_Between_Repetitions": 60,
                "Intervention_Config": {
                    "class": "SimpleBednet",
                    "Cost_To_Consumer": 5,
                    "Usage_Config": {
                        "class": "WaningEffectRandomBox",
                        "Initial_Effect": 1.0,
                        "Expected_Discard_Time" : 60
                    },
                    "Blocking_Config": {
                        "class": "WaningEffectExponential",                        
                        "Decay_Time_Constant": 150,
                        "Initial_Effect": 0.5
                    },
                    "Killing_Config": {
                        "class": "WaningEffectConstant",
                        "Initial_Effect": 1.0
                    }
                }
            }
        }
    ],
    "Use_Defaults": 1
}
WaningEffectBox

The efficacy is held at a constant rate until it drops to zero after the user-defined duration.

{
    "Intervention_Config": {
        "Blocking_Config": {
            "Box_Duration": 3650,
            "Initial_Effect": 0,
            "class": "WaningEffectBox"
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Box_Duration

float

0

100000

100

The box duration of the effect in days.

 
{
    "Box_Duration": 40
}

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant until the duration is complete, as specified with the Box_Duration parameter for the WaningEffectBox class.

 
{
    "Waning_Config": {
        "Box_Duration": 10,
        "Initial_Effect": 0.75,
        "class": "WaningEffectBox"
    }
}
WaningEffectBoxExponential

The initial efficacy is held for a specified duration, then the efficacy decays at an exponential rate where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant.

  {
    "Intervention_Config": {
        "Reduction_Config": {
            "class": "WaningEffectBoxExponential",
            "Box_Duration": 100,
            "Decay_Time_Constant": 150,
            "Initial_Effect": 0.1
        }
    }
  }

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Box_Duration

float

0

100000

100

The box duration of the effect in days.

 
{
    "Box_Duration": 3650,
    "Initial_Effect": 0.97,
    "Decay_Time_Constant": 50
}

Decay_Time_Constant

float

0

100000

100

The exponential decay length, in days, where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
    "Box_Duration": 3650,
    "Initial_Effect": 0.97,
    "Decay_Time_Constant": 50
}

Initial_Effect

float

0

1

1

The initial efficacy, held for a duration as specified with the Box_Duration parameter and then decaying at an exponential length (in days), where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
    "Box_Duration": 3650,
    "Initial_Effect": 0.97,
    "Decay_Time_Constant": 50
}
WaningEffectCombo

The WaningEffectCombo class is used within individual-level interventions and allows for specifiying a list of effects when the intervention only has one WaningEffect defined. These effects can be added or multiplied.

{
    "class" : "WaningEffectCombo",
    "Add_Effects" : 1,
    "Expires_When_All_Expire" :0,
    "Effect_List" : [
        {
            "class": "WaningEffectMapLinear",
            "Initial_Effect" : 1.0,
            "Expire_At_Durability_Map_End" : 1,
            "Durability_Map" :
            {
                "Times"  : [ 0.0, 1.0, 2.0 ],
                "Values" : [ 0.2, 0.4, 0.6 ]
            }
        },
        {
            "class": "WaningEffectBox",
            "Initial_Effect": 0.5,
            "Box_Duration" : 5.0
        }
    ]
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant when using with the WaningEffectConstant class.

 
{
    "Waning_Config": {
        "Initial_Effect": 0.65,
        "class": "WaningEffectConstant"
    }
}
WaningEffectConstant

The efficacy is held at a constant rate.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Killing_Config": {
            "class": "WaningEffectConstant",
            "Initial_Effect": 1.0
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant when using with the WaningEffectConstant class.

 
{
    "Waning_Config": {
        "Initial_Effect": 0.65,
        "class": "WaningEffectConstant"
    }
}
WaningEffectExponential

The efficacy decays at an exponential rate where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Blocking_Config": {
            "class": "WaningEffectExponential",            
            "Decay_Time_Constant": 150,
            "Initial_Effect": 0.5
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Decay_Time_Constant

float

0

100000

100

The exponential decay length, in days, where the current effect is equal to 1 - dt/Decay_Time_Constant (dt equal to delta time).

 
{
    "Decay_Time_Constant": 30,
    "Initial_Effect": 0.95
}

Initial_Effect

float

0

1

1

The initial efficacy, held for a specified duration (in days) as specified with the Box_Duration parameter. After this duration the efficacy decays at an exponential decay length (in days), where the current effect is equal to Initial_Effect - dt/Decay_Time_Constant (dt equal to delta time).

 
{
    "Waning_Config": {
        "Decay_Time_Constant": 0.87,
        "Initial_Effect": 0.9,
        "class": "WaningEffectExponential"
    }
}
WaningEffectMapLinear

The efficacy decays based on the time since the start of the intervention. This change is defined by a map of time to efficacy values in which the time between time/value points is linearly interpolated. When the time since start reaches the end of the times in the map, the last value will be used unless the intervention expires. If the time since start is less than the first value in the map, the efficacy will be zero. This can be used to define the shape of a curve whose magnitude is defined by the Initial_Effect multiplier.

 {
    "Intervention_Config": {
        "class": "ControlledVaccine",
        "Waning_Config": {
            "class": "WaningEffectMapLinear",
            "Reference_Timer": 0,
            "Initial_Effect": 1.0,
            "Expire_At_Durability_Map_End": 1,
            "Durability_Map": {
                "Times": [0, 120, 240, 360],
                "Values": [0.7, 0.8, 1.0, 0.0]
            }
        }
    }
 }

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

JSON object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
    "Durability_Map": {
        "Times": [
            0.0,
            20.0,
            21.0,
            30.0,
            31.0,
            365.0
        ],
        "Values": [
            1.0,
            1.0,
            0.0,
            0.0,
            1.0,
            1.0
        ]
    }
}

Expire_At_Durability_Map_End

boolean

0

1

0

Set to 1 to let the intervention expire when the end of the map is reached.

 
{
    "Expire_At_Durability_Map_End": 1
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinear class.

 
{
    "Waning_Config": {
        "Durability_Map": {
            "Times": [
                0,
                30,
                60,
                90,
                120
            ],
            "Values": [
                0.9,
                0.3,
                0.9,
                0.6,
                1
            ]
        },
        "Expire_At_Durability_Map_End": 0,
        "Initial_Effect": 1,
        "class": "WaningEffectMapLinear"
    }
}

Reference_Timer

integer

0

2147480000.0

0

The timestamp at which linear-map should be anchored.

 
{
    "Reference_Timer": 1
}

Times

array of floats

0

999999

NA

An array of days.

 
{
    "Durability_Map": {
        "Times": [
            0,
            385,
            390,
            10000
        ],
        "Values": [
            0,
            0.0,
            0.5,
            0.5
        ]
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}
WaningEffectMapLinearAge

Similar to WaningEffectMapLinear, except that the efficacy decays based on the age of the individual who owns the intervention instead of the time since the start of the intervention.

{
  "class": "WaningEffectMapLinearAge",
  "Initial_Effect": 1,
  "Durability_Map": {
    "Times": [
      1,
      2,
      5,
      7
    ],
    "Values": [
      1,
      0.75,
      0.5,
      0.25
    ]
  }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

JSON object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
    "Durability_Map": {
        "Times": [
            1,
            2,
            5,
            7
        ],
        "Values": [
            1,
            0.75,
            0.5,
            0.25
        ]
    }
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinearAge class.

 
{
    "class": "WaningEffectMapLinearAge",
    "Initial_Effect": 1,
    "Durability_Map": {
        "Times": [
            1,
            2,
            5,
            7
        ],
        "Values": [
            1,
            0.75,
            0.5,
            0.25
        ]
    }
}

Times

array of floats

0

125

NA

An array of years.

 
{
    "Durability_Map": {
        "Times": [
            1,
            2,
            5,
            7
        ],
        "Values": [
            1,
            0.75,
            0.5,
            0.25
        ]
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Durability_Map": {
        "Times": [
            1,
            2,
            5,
            7
        ],
        "Values": [
            1,
            0.75,
            0.5,
            0.25
        ]
    }
}
WaningEffectMapLinearSeasonal

Similar to WaningEffectMapLinear, except that the map will repeat itself every 365 days. That is, the time since start will reset to zero once it reaches 365. This allows you to simulate seasonal effects.

{
    "Intervention_Config": {
        "class": "UsageDependentBednet",
        "Usage_Config_List": [{
            "class": "WaningEffectMapLinearSeasonal",
            "Initial_Effect": 1.0,
            "Durability_Map": {
                "Times": [0.0, 20.0, 21.0, 30.0, 31.0, 365.0],
                "Values": [1.0, 1.0, 0.0, 0.0, 1.0, 1.0]
            }
        }]
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

JSON object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
    "Durability_Map": {
        "Times": [
            0.0,
            20.0,
            21.0,
            30.0,
            31.0,
            365.0
        ],
        "Values": [
            1.0,
            1.0,
            0.0,
            0.0,
            1.0,
            1.0
        ]
    }
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapLinearSeasonal class.

 
{
    "class": "WaningEffectMapLinearSeasonal",
    "Initial_Effect": 1,
    "Durability_Map": {
        "Times": [
            0,
            20,
            21,
            30,
            31,
            365
        ],
        "Values": [
            1,
            1,
            0,
            0,
            1,
            1
        ]
    }
}

Times

array of floats

0

365

NA

An array of days.

 
{
    "Durability_Map": {
        "Times": [
            0.0,
            20.0,
            21.0,
            30.0,
            31.0,
            365.0
        ],
        "Values": [
            1.0,
            1.0,
            0.0,
            0.0,
            1.0,
            1.0
        ]
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}
WaningEffectMapPiecewise

Similar to WaningEffectMapLinear, except that the data is assumed to be constant between time/value points (no interpolation). If the time since start falls between two points, the efficacy of the earlier time point is used.

{
    "Intervention_Config": {
        "class": "SimpleVaccine",
        "Waning_Config": {
            "class": "WaningEffectMapPiecewise",
            "Initial_Effect": 1.0,
            "Reference_Timer": 0,
            "Expire_At_Durability_Map_End": 0,
            "Durability_Map": {
                "Times": [10, 30, 50],
                "Values": [0.9, 0.1, 0.6]
            }
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Durability_Map

JSON object

NA

NA

NA

The time, in days, since the intervention was distributed and a multiplier for the Initial_Effect.

 
{
    "Durability_Map": {
        "Times": [
            0.0,
            20.0,
            21.0,
            30.0,
            31.0,
            365.0
        ],
        "Values": [
            1.0,
            1.0,
            0.0,
            0.0,
            1.0,
            1.0
        ]
    }
}

Expire_At_Durability_Map_End

boolean

0

1

0

Set to 1 to let the intervention expire when the end of the map is reached.

 
{
    "Expire_At_Durability_Map_End": 1
}

Initial_Effect

float

0

1

1

The multiplier used to define the magnitude of the shape of the curve, as specified when using the parameters with the WaningEffectMapPiecewise class.

 
{
    "Waning_Config": {
        "Durability_Map": {
            "Times": [
                10,
                30,
                50
            ],
            "Values": [
                0.9,
                0.1,
                0.6
            ]
        },
        "Expire_At_Durability_Map_End": 0,
        "Initial_Effect": 1,
        "class": "WaningEffectMapPiecewise"
    }
}

Reference_Timer

integer

0

2147480000.0

0

The timestamp at which linear-map should be anchored.

 
{
    "Reference_Timer": 1
}

Times

array of floats

0

999999

NA

An array of days.

 
{
    "Durability_Map": {
        "Times": [
            0,
            385,
            390,
            10000
        ],
        "Values": [
            0,
            0.0,
            0.5,
            0.5
        ]
    }
}

Values

array of floats

0

3.40282e+38

NA

An array of values to match the defined Times.

 
{
    "Times": [
        1998,
        2000,
        2003,
        2006,
        2009
    ],
    "Values": [
        0,
        0.26,
        0.08,
        0.14,
        0.54
    ]
}
WaningEffectRandomBox

The efficacy is held at a constant rate until it drops to zero after a user-defined duration. This duration is randomly selected from an exponential distribution where Expected_Discard_Time is the mean.

{
    "Intervention_Config": {
        "class": "SimpleBednet",
        "Cost_To_Consumer": 5,
        "Usage_Config": {
            "class": "WaningEffectRandomBox",
            "Initial_Effect": 1.0,
            "Expected_Discard_Time": 60
        }
    }
}

Parameter

Data type

Minimum

Maximum

Default

Description

Example

Expected_Discard_Time

float

0

100000

100

The mean time, in days, of an exponential distribution of the duration of the effect of an intervention (such as a vaccine or bed net). Specify how this effect decays over time using one of the Waning effect classes.

 
{
    "Expected_Discard_Time": 60
}

Initial_Effect

float

0

1

1

Strength of the effect, which remains constant until the duration is complete when using with the WaningEffectRandomBox class.

 
{
    "Waning_Config": {
        "Expected_Discard_Time": 65,
        "Initial_Effect": 0.85,
        "class": "WaningEffectRandomBox"
    }
}
Targeting_Config classes

The following classes can be used to enhance the selection of people when distributing interventions. Most event coordinators and node-level interventions that distribute interventions to people have a parameter called Targeting_Config. This allows you to not only target individuals based on their gender, age, and IndividualProperties (See NodeProperties and IndividualProperties parameters for more information), but also on things such as whether or not they have a particular intervention or are in a relationship.

Note

Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false. Minimum, maximum, or default values of “NA” indicate that those values are not applicable for that parameter.

EMOD does not use true defaults; that is, if the dependency relationships indicate that a parameter is required, you must supply a value for it. However, many of the tools used to work with EMOD will use the default values provided below.

JSON format does not permit comments, but you can add “dummy” parameters to add contextual information to your files. Any keys that are not EMOD parameter names will be ignored by the model.

Below is a simple example where we want to distribute a vaccine to 20% of the people that do not already have the vaccine on the 100th day of the simulation.

{
    "class": "CampaignEvent",
    "Start_Day": 100,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.2,
        "Targeting_Config": {
            "class": "HasIntervention",
            "Is_Equal_To": 0,
            "Intervention_Name": "MyVaccine"
        },
        "Intervention_Config": {
            "class": "SimpleVaccine",
            "Intervention_Name" : "MyVaccine",
            "Cost_To_Consumer": 1,
            "Vaccine_Take": 1,
            "Vaccine_Type": "AcquisitionBlocking",
            "Waning_Config": {
                "class": "WaningEffectConstant",
                "Initial_Effect" : 1.0
            }
        }
    }
}

Below is a slightly more complicated example where we want to distribute a diagnostic to people that are either high risk or have not been vaccinated.

{
    "class": "CampaignEvent",
    "Start_Day": 100,
    "Nodeset_Config": {
        "class": "NodeSetAll"
    },
    "Event_Coordinator_Config": {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Target_Demographic": "Everyone",
        "Demographic_Coverage": 0.2,
        "Targeting_Config": {
            "class" : "TargetingLogic",
            "Logic" : [
                [
                    {
                        "class": "HasIntervention",
                        "Is_Equal_To": 0,
                        "Intervention_Name": "MyVaccine"
                    }
                ],
                [
                    {
                        "class": "HasIP",
                        "Is_Equal_To": 1,
                        "IP_Key_Value": "Risk:HIGH"
                    }
                ]
            ]
        },
        "Intervention_Config": {
            "class": "SimpleDiagnostic",
            "Treatment_Fraction": 1.0,
            "Base_Sensitivity": 1.0,
            "Base_Specificity": 1.0,
            "Event_Or_Config": "Event",
            "Positive_Diagnosis_Event": "TestedPositive"
        }
    }
}
HasIntervention

This determines whether or not the individual has an intervention with the given name. This will only work for interventions that persist like SimpleVaccine and DelayedIntervention. It will not work for interventions like BroadcastEvent since it does not persist.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected.

Intervention_Name

string

(no default)

The name of the intervention the person should have. This cannot be an empty string but should be either the name of the class or the name given to the intervention of interest using the parameter Intervention_Name. EMOD does not verify that this name exists.
Example

Select the person if they do NOT have the MyVaccine intervention.

"Targeting_Config": {
    "class": "HasIntervention",
    "Is_Equal_To": 0,
    "Intervention_Name": "MyVaccine"
}
HasIP

This determines if the person has a particular value of a particular IndividualProperties (IP). This is especially needed when determining if a partner has a particular IP (see HasRelationship).

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected.

IP_Key_Value

string

(no default)

This is the normal IndividualProperties ‘Key:Value’ pair where the key/property name and one of its values is separated by a colon (‘:’).
Example

Select the person if their Risk property is HIGH.

"Targeting_Config": {
    "class": "HasIP",
    "Is_Equal_To": 1,
    "IP_Key_Value": "Risk:HIGH"
}
TargetingLogic

In some cases, the you need to logically combine multiple restrictions. In these situations, you should use the TargetingLogic class where you can “and” and “or” the different questions.

NOTE: Each element is independent and is being asked of the individual in question. For questions that are about a partner of the individual, all of the qualifiers for that partner must be in the element. This will ensure that there is one partner that has all of the qualifications. Otherwise, you could have a situation where one partner satisfies one qualification and another partner satisfies a different one, but no partner has all of the qualifications.

Configuration

Parameter

Data type

Min

Max

Default

Description

Logic

2D array of JSON objects

(no default)

This is a two-dimensional array of JSON objects. The elements of the inner array will be AND’d together while the arrays themselves will be OR’d. This is similar to Property_Restrictions_Within_Node. This array and the inner arrays cannot be empty.
Example

Select the person if they do not have the MyVaccine intervention OR do not have their Risk property set to HIGH. Notice that Logic 2x1 where the first dimention contains two arrays with one JSON object. These two arrays are OR’d together.

"Targeting_Config": {
    "class" : "TargetingLogic",
    "Logic" : [
        [
            {
                "class": "HasIntervention",
                "Is_Equal_To": 0,
                "Intervention_Name": "MyVaccine"
            }
        ],
        [
            {
                "class": "HasIP",
                "Is_Equal_To": 0,
                "IP_Key_Value": "Risk:HIGH"
            }
        ]
    ]
}

Select the person if they do not have the MyVaccine intervention AND do not have their Risk property set to HIGH. Notice that Logic is 1x2 where the first dimension contains a single array with two JSON objects. These two objects are AND’d together.

"Targeting_Config": {
    "class" : "TargetingLogic",
    "Logic" : [
        [
            {
                "class": "HasIntervention",
                "Is_Equal_To": 0,
                "Intervention_Name": "MyVaccine"
            },
            {
                "class": "HasIP",
                "Is_Equal_To": 0,
                "IP_Key_Value": "Risk:HIGH"
            }
        ]
    ]
}
IsCircumcised

This determines if the man has been circumcised or not.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected.
Example

Select the person if they are NOT circumcised.

"Targeting_Config": {
    "class": "IsCircumcised",
    "Is_Equal_To": 0
}
IsHivPositive

This determines if the individual has HIV.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

And_Has_Ever_Been_Tested

enum

NO

YES

NA

If the user sets this Enum to YES, then the individual’s true infection status must equal Is_Equal_To and the person must have been tested at least once. Notice that this only tells if the person has been tested, NOT that they tested positive. If NA, then do not include this as part of the check.

And_Has_Ever_Tested_Positive

enum

NO

YES

NA

If the user sets this Enum to YES, then the individual’s true infection status must equal Is_Equal_To and the person must have tested POSITIVE at least once. Notice that this is different than just having been tested. However, it does not say the person received the results. If NA, then do not include this as part of the check.

And_Has_Recieved_Positive_Results

enum

NO

YES

NA

If the user sets this Enum to YES, then the individual’s true infection status must equal Is_Equal_To and the last test result received was positive.
Example

Select the person if they have HIV, have been tested, and have tested positive. The ‘NA’ for And_Has_Received_Positive_Results means we are not concerned whether or not they received the results.

"Targeting_Config": {
    "class" : "IsHivPositive",
    "Is_Equal_To": 1,
    "And_Has_Ever_Been_Tested": "YES",
    "And_Has_Ever_Tested_Positive": "YES",
    "And_Has_Received_Positive_Results": "NA"
}
IsOnART

Determine if the individual is actively on ART.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.
Example

Select the person if they are NOT on ART.

"Targeting_Config": {
    "class" : "IsOnART",
    "Is_Equal_To": 0
}
HasBeenOnArtMoreOrLessThanNumMonths

Determine if the individual has been on ART for less than “num” months. It will be false if the individual is not on ART. The test will be strictly less than.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

Num_Months

float

0

1500

1500

This is the number of months that will be used in the test. The individual’s duration on ART must be more or less than this value. NOTE: 1500 months is about 12 months / year * 125 years of max age

More_Or_Less

enum

LESS

MORE

LESS

This is used to determine if the check should be less than or greater than.
Example

Select the person if they have been on ART for more than 6 months.

"Targeting_Config": {
    "class" : "HasBeenOnArtMoreOrLessThanNumMonths",
    "Is_Equal_To": 1,
    "More_Or_Less": "MORE",
    "Num_Months": 6
}
HasMoreOrLessThanNumPartners

Determine if the individual has more than “num” active partners. This includes relationships that are paused due to migration. This test is strictly more or less than.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

Num_Partners

integer

0

62

0

This parameter allows the user to set the number of active partners/relationships that the individual must have more or less of.

Of_Relationship_Type

enum

NA

If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have more or less relationships of this type. When the value is set to NA (default), then it will count the relationships regardless of type.

More_Or_Less

enum

LESS

MORE

LESS

This is used to determine if the check should be less than or greater than.
Example

Select the person if they have more than eight partners of any type.

"Targeting_Config": {
    "class": "HasMoreOrLessThanNumPartners",
    "Is_Equal_To": 1,
    "Of_Relationship_Type": "NA",
    "Num_Partners": 8,
    "More_Or_Less": "MORE"
}

Select the person if they have less than three transitory partners.

"Targeting_Config": {
    "class": "HasMoreOrLessThanNumPartners",
    "Is_Equal_To": 1,
    "Of_Relationship_Type": "TRANSITORY",
    "Num_Partners": 3,
    "More_Or_Less": "LESS"
}
HasHadMultiplePartnersInLastNumMonths

Determine if the individual has had more than one relationship in the last “Num” months. This could constitute as “high-risk” behavior. The goal is to target people that have had coital acts with more than one person during the last X months. This would count current relationships, relationships that started in the last X months, and relationships that have ended in the last X months. Basically, all the relationships that have been active at some point during the last X months. NOTE: This only counts unique partners. Two relationships with the same person during the time period will count as one.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

Num_Months_Type

enum

THREE_MONTHS

This parameter allows the user to set the maximum number of months from the current day to consider if the individual had multiple relationships. NumMonthsType Enum - THREE_MONTHS, SIX_MONTHS, NINE_MONTHS, TWELVE_MONTHS

Of_Relationship_Type

enum

NA

If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have more or less relationships of this type. When the value is set to NA (default), then it will count the relationships regardless of type.
Example

Select the person if they have NOT had multiple INFORMAL partners in the last six months.

"Targeting_Config": {
    "class" : "HasHadMultiplePartnersInLastNumMonths",
    "Is_Equal_To": 0,
    "Num_Months_Type": "SIX_MONTHS",
    "Of_Relationship_Type": "INFORMAL"
}

Select the person if they have had multiple partners in the last year but not necessarily at the same time.

"Targeting_Config": {
    "class" : "HasHadMultiplePartnersInLastNumMonths",
    "Is_Equal_To": 1,
    "Num_Months_Type": "TWELVE_MONTHS",
    "Of_Relationship_Type": "NA"
}
HasCd4BetweenMinAndMax

Determine if the individual has a CD4 count that is between “min” and “max”. The test is inclusive for “min” and exclusive for “max”.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

Min_CD4

float

0

1999

0

The minimum value of the test range. The individual’s CD4 can be equal to this value to be considered ‘between’.

Max_CD4

float

1

2000

2000

The maximum value of the test range. The individual’s CD4 must be strictly less than this value to be considered ‘between’.
Example

Select the person if their CD4 is currently between 530 and 600. In other words, 530 <= current CD4 < 600.

"Targeting_Config": {
    "class" : "HasCd4BetweenMinAndMax",
    "Is_Equal_To": 1,
    "Min_CD4": 530.0,
    "Max_CD4": 600.0
}
HasRelationship

This is used to select people who have a partner/relationship that meets certain qualifications. Except for when That_Recently = ENDED, the restriction will be considering all of the relationships.

That_Recently can have one of the following values:

  • NA - Default - Do no consider That_Recently in the selection process.

  • STARTED - Only consider relationships that have started within one time-step. One should note that the relationships you see will depend on whether you are using NodeLevelHealthTriggeredIV (NLHTIV) or an event coordinator. NLHTIV and the individuals will be updated after new relationships have been created so with this feature, NLHTIV will see relationships in the previous time step as well as the current time step. An event coordinator executes BEFORE new relationships are formed so it will only see the relationships created in the previous time step.

  • ENDED - Check the status of the relationship that just ended. THIS CAN ONLY BE USED WITH A NodeLevelHealthTriggeredIV LISTENING FOR THE ExitedRelatinship EVENT.

Configuration

Parameter

Data type

Min

Max

Default

Description

Is_Equal_To

boolean

0

1

1

This is used to determine if the individual is selected based on the result of the value of the question. For example, if the user wants to select individuals that are NOT circumcised, the user will set this parameter to false (0). If the return value of the question ‘is equal to’ the value of this parameter, the individual is selected. If NA, then do not include this as part of the check.

Of_Relationship_Type

enum

NA

If the user sets this value to one of the four specific types (TRANSITORY, INFORMAL, MARITAL, COMMERCIAL), then the individual must have more or less relationships of this type. When the value is set to NA (default), then it will count the relationships regardless of type.

That_Recently

enum

NA

This parameter is used if the relationship being consider must have recently been started or ended.

With_Partner_Who

JSON object

{}

Given that the parameters about the relationship are true, this parameter is used to look at the partner of the relationship. It is a Targeting_Config so one uses the same classes to query the partner. For example, to find out if person has a partner with HIV, you could use IsHivPositive.
Examples

Select the person if they have a partner that has HIV.

"Targeting_Config": {
    "class" : "HasRelationship",
    "Is_Equal_To": 1,
    "Of_Relationship_Type":  "NA",
    "That_Recently":  "NA",
    "With_Partner_Who" : {
        "class" : "IsHivPositive",
        "Is_Equal_To" : 1
    }
}

Select the person if they have recently started a marital relationship with someone who is taking ART.

"Targeting_Config": {
    "class" : "HasRelationship",
    "Is_Equal_To": 1,
    "Of_Relationship_Type":  "MARITAL",
    "That_Recently":  "STARTED",
    "With_Partner_Who" : {
        "class" : "IsOnART",
        "Is_Equal_To" : 1
    }
}

Test a person for HIV if they have recently ended a martial relationship where the partner had tested positive for HIV.

{
    "class": "CampaignEvent",
    "Start_Day": 140,
    "Nodeset_Config": { "class": "NodeSetAll" },
    "Event_Coordinator_Config":
    {
        "class": "StandardInterventionDistributionEventCoordinator",
        "Intervention_Config":
        {
            "class": "NodeLevelHealthTriggeredIV",
            "Target_Demographic": "Everyone",
            "Trigger_Condition_List": [
                "ExitedRelationship"
            ],
            "Targeting_Config" :
            {
                "class" : "HasRelationship",
                "Is_Equal_To": 1,
                "Of_Relationship_Type":  "MARITAL",
                "That_Recently":  "ENDED",
                "With_Partner_Who" : {
                    "class" : "IsHivPositive",
                    "Is_Equal_To" : 1,
                    "And_Has_Ever_Been_Tested": "YES",
                    "And_Has_Ever_Tested_Positive": "YES",
                    "And_Has_Received_Positive_Results": "NA"
                }
            },
            "Actual_IndividualIntervention_Config": {
                "class": "HIVRapidHIVDiagnostic"
                "Positive_Diagnosis_Event": "Tested_Positive",
                "Negative_Diagnosis_Event": "Tested_Negative"
            }
        }
    }
}

Imagine you want to select people to stop using PrEP because they either don’t have any HIV postive partners or their partner is virally surpressed because they been on ART for more than 6 months. You would then want to select individuals that are HIV Negative, are on PrEP, and either have no HIV Positive partners or their HIV Positive partners have been on ART for more than 6 months.

Notice how HasRelationship is “or’ing” HIV positive and not on ART with HIV postive and on ART less than 6 months and then taking the negative of that. Something like:

  • not( (HIV+ & not OnART) or (HIV+ & (OnART < 6 monts) )

"Targeting_Config" :
{
   "class" : "TargetingLogic",
   "Logic":
   [
      [
         {
            "class" : "IsHivPositive",
            "Is_Equal_To" : 0
         },
         {
            "class" : "HasIntervention",
            "Intervention_Name" : "PrEP",
            "Is_Equal_To" : 1
         },
         {
            "class" : "HasRelationship",
            "Is_Equal_To" : 0
            "With_Partner_Who" :
            {
               "class" : "TargetingLogic",
               "Logic":
               [
                  [
                     {
                        "class" : "IsHivPositive",
                        "Is_Equal_To" : 1,
                        "And_Has_Ever_Tested_Positive": "YES"
                     },
                     {
                        "class" : "IsOnART",
                        "Is_Equal_To" : 0
                     }
                  ],
                  [
                     {
                        "class" : "IsHivPositive",
                        "Is_Equal_To" : 1,
                        "And_Has_Ever_Tested_Positive": "YES"
                     },
                     {
                        "class" : "HasBeenOnArtMoreOrLessThanNumMonths",
                        "Is_Equal_To" : 1,
                        "More_Or_Less" : "LESS",
                        "Num_Months" : 6.0
                     }
                  ]
               ]
            }
         }
      ]
   ]
}
Event list

The following list provides possible values for built-in events. These events can be broadcast to nodes to trigger interventions. You can also broadcast custom events, but the event names must be listed in the Custom_Individual_Events configuration parameter.

Note

Not all events are appropriate for every simulation type.

  • Births

  • DiseaseDeaths

  • EighteenMonthsOld

  • Emigrating

  • EnteredRelationship

  • EveryTimeStep

  • EveryUpdate

  • ExitedRelationship

  • ExposureComplete

  • FirstCoitalAct

  • FourteenWeeksPregnant

  • GaveBirth

  • HappyBirthday

  • HIVNewlyDiagnosed

  • HIVTestedNegative

  • HIVTestedPositive

  • HumanToVectorTransmission

  • Immigrating

  • InfectionCleared

  • InterventionDisqualified

  • NewClinicalCase

  • NewExternalHIVInfection

  • NewInfectionEvent

  • NewlySymptomatic

  • NewSevereCase

  • NodePropertyChange

  • NonDiseaseDeaths

  • OpportunisticInfectionDeath

  • Pregnant

  • PropertyChange

  • ProviderOrdersTBTest

  • ReceivedInfectiousBites

  • SixWeeksOld

  • StartedART

  • STIDebut

  • STIExposed

  • STINewInfection

  • STIPostImmigrating

  • STIPreEmigrating

  • StoppedART

  • SymptomaticCleared

  • TBActivation

  • TBActivationExtrapulm

  • TBActivationPostRelapse

  • TBActivationPresymptomatic

  • TBActivationSmearNeg

  • TBActivationSmearPos

  • TBFailedDrugRegimen

  • TBMDRTestDefault

  • TBMDRTestNegative

  • TBMDRTestPositive

  • TBPendingRelapse

  • TBRelapseAfterDrugRegimen

  • TBRestartHSB

  • TBStartDrugRegimen

  • TBStopDrugRegimen

  • TBTestDefault

  • TBTestNegative

  • TBTestPositive

  • TestPositiveOnSmear

  • TwelveWeeksPregnant

  • VectorToHumanTransmission

  • WouldHaveDied

  • WouldHaveHadAIDS

  • WouldHaveEnteredLatentStage

Generate a list of all available parameters (a schema)

You can generate a schema from the EMOD executable (Eradication.exe) or Eradication binary for Linux that defines all configuration parameters and campaign parameters available in the version of EMOD that is installed, for all available simulation types. This includes parameter names, data types, defaults, ranges, and short descriptions. The schema does not include demographics parameters.

Logging information is also produced as part of the schema. If you are using EMOD source and have added or modified configuration parameters or intervention code, this logging information can help you troubleshoot any errors that may occur.

Warning

If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.

Command options

The following command-line options are available for providing information about EMOD.

EMOD information commands

Long form

Short form

Description

--help

-help

Shows help options for Eradication.exe.

--version

-v

Shows the version information and supported simulation types. Note capitalization of short alternative.

--get-schema

--get-schema

Outputs the configuration and campaign parameters. Unless --schema-path or a redirect operator is used, the schema will print to the Command Prompt window.

--schema-path

>

When used with --get-schema, if a TXT or JSON file is specified, the schema information will be written to the file instead of the Command Prompt window.
Usage

  1. Open a Command Prompt window and navigate to the directory where Eradication.exe is installed.

  2. To output the schema to the Command Prompt window, enter:

    Eradication.exe --get-schema

  3. To output the schema to a file, do one of the following (replacing <filename> with the desired filename):

    • To output a text file that includes logging information, enter:

      Eradication.exe --get-schema > <filename>.txt

    • To display logging in the Command Prompt window and output a text file that does not include logging information, enter:

      Eradication.exe --get-schema --schema-path <filename>.txt

    • To output the schema to a JSON file that includes logging information, enter:

      Eradication.exe --get-schema > <filename>.json

    • To display logging in the Command Prompt window and output a JSON file that does not include logging information, enter:

      Eradication.exe --get-schema --schema-path <filename>.json

Frequently asked questions

Why doesn’t anything happen when I double-click Eradication.exe?

Unlike many executable files, Eradication.exe does not open a software installer when double-clicked. Instead, you must provide Eradication.exe with various input files used to run a simulation and create outputs. You can run simulations in a number of ways. The simplest way to learn about the model is to run individual simulations at the command line. However, because EMOD is a stochastic model, this is not feasible when you must run many simulations to create useful output for statistical analysis. Once you advance to that stage, you will want to use other software tools to run multiple simulations either locally or, more often, on an HPC cluster. For more information, see EMOD installation and Running a simulation.

Where do I get demographics and climate files?

IDM provides demographics and climate files for many different regions of the world in the EMOD-InputData GitHub repository. See EMOD installation for download instructions. If there are no files available for the region you are interested in, contact support@idmod.org.

How do I plot my output?

EMOD does not produce plots of the data by default. Instead, it produces JSON (JavaScript Object Notation) or CSV files that you can then parse and plot using Python, MATLAB, R, or another programming language. The EMOD scenarios zip file contains input files and plotting scripts for many different disease modeling scenarios intended to teach EMOD. You may want to review these files to see examples of how the output can be plotted.

Does your model include X?

Many aspects of disease dynamics are explicitly modeled in EMOD. Review EMOD parameter reference for an exhaustive list of all parameters that can be used to enable functionality in EMOD. If you want to model something that isn’t listed there, EMOD provides highly flexible functionality with the individual and node property feature. These properties label individuals or regional nodes in a simulation so you can change disease outbreaks, transmission dynamics, behavior, or treatment based on the assigned values. For example, you can add properties to represent vitamin deficiencies, comorbidities, and more. For more information, see Individual and node properties.

If individual and node properties cannot incorporate the functionality you need, EMOD is open-source software that can be extended to meet your needs. For more information, see EMOD source code installation.

Can I model regions, countries, provinces, or cities?

EMOD uses nodes to represent geographic areas. Each node has a population and associated characteristics. Individuals and, if relevant, vectors can migrate between nodes. Nodes can represent areas of any scale you like, from entire countries to individual households.

Do you have a model for disease X?

The software architecture of EMOD has a “generic model” base upon which more specific transmission modes and diseases are built. This allows common functionality to be shared for modeling a variety of diseases. For example, the generic model can be used to model influenza, measles, and more. You can also use one of the transmission mode simulation types (airborne, STI, environmental, vector) to model diseases such as herpes, typhoid, dengue or others that we don’t explicitly support. Often, this can be done without the need to make any source code changes.

Glossary

The Epidemiological MODeling software (EMOD) glossary is divided into the following subsections that define terms related to software usage, general epidemiology, and the particular disease being modeled.

Epidemiology terms

antibodies

See antibody.

antibody

A blood protein produced in response to and counteracting a specific antigen. Antibodies combine chemically with substances that the body recognizes as foreign (eg. bacteria, viruses, or other substances).

antigen

A substance that is capable of inducing a specific immune response and that evokes the production of one or more antibodies.

antigens

See antigen.

Clausius-Clayperon relation

A way of characterizing a transition between two phases of matter; provides a method to find a relationship between temperature and pressure along phase boundaries. Frequently used in meteorology and climatology to describe the behavior of water vapor. See Wikipedia - Clausius-Clayperon relation for more information.

compartmental model

A disease model that divides the population into a number of compartments that represent different disease states, such as susceptible, infected, or recovered. Every person in a compartment is considered identical. Many compartmental models are deterministic, but some are stochastic.

deterministic

Characterized by the output being fully determined by the parameter values and the initial conditions. Given the same inputs, a deterministic model will always produce the same output.

diffusive migration

The diffusion of people in and out of nearby nodes by foot travel.

disability-adjusted life years (DALY)

The number of years of life lost due to premature mortality plus the years lost due to disability while infected. Used to quantify the burden of disease.

epidemic

An outbreak of an infectious disease, such that a greater number of individuals than normal has the disease. Epidemics have very high R0 (Recall R0>1 for a disease to spread) and are often associated with acute, highly transmissible pathogens that can be directly transmitted. Further, pathogens with lower infectious periods create more explosive epidemics. To control epidemics, it is necessary to reduce R0. This can be done by:

  • Reducing transmissibility.

  • Decreasing the number of susceptibles (by vaccination, for example).

  • Decreasing the mean number of contacts or the transmissibility, such as by improving sanitation, or limiting the number of interactions sick people have with healthy people.

  • Reducing the length of the infectious period.

epitope

The portion of an antigen that the immune system recognizes. An epitope is also called an antigenic determinant.

Euler method

Used in mathematics and computational science, this method is a first-order numerical procedure for solving ordinary differential equations with a given initial value.

exp(

The exponential function, \(e^x\), where \(e\) is the number (approximately 2.718281828) such that the function \(e^x\) is its own derivative. The exponential function is used to model a relationship in which a constant change in the independent variable gives the same proportional change (i.e. percentage increase or decrease) in the dependent variable. The function is often written as \(exp(x)\). The graph of \(y = exp(x)\) is upward-sloping and increases faster as \(x\) increases.

exposed

Individual who has been infected with a pathogen, but due to the pathogen’s incubation period, is not yet infectious.

force of infection (FoI)

A measure of the degree to which an infected individual can spread infection; the per-capita rate at which susceptibles contract infection. Typically increases with transmissibility and prevalence of infection.

herd immunity

The resistance to the spread of a contagious disease within a population that results if a sufficiently high proportion of individuals are immune to the disease, especially through vaccination. The portion of the population that needs to be immunized in order to achieve herd immunity is P > 1 – (1/ R0), where P = proportion vaccinated * vaccine efficacy.

immune

Unable to become infected/infectious, whether through vaccination or having the disease in the past.

incidence

The rate of new cases of a disease during a specified time period. This is a measure of the risk of contracting a disease.

infectious

Individual who is infected with a pathogen and is capable of transmitting the pathogen to others.

Koppen-Geiger Climate Classification System

A system based on the concept that native vegetation is a good expression of climate. Thus, climate zone boundaries have been selected with vegetation distribution in mind. It combines average annual and monthly temperatures and precipitation, and the seasonality of precipitation. EMOD has several options for configuring the climate, namely air temperature, rainfall, and humidity.

One option utilizes input files that associate geographic nodes with Koppen climate indices. The modified Koppen classification uses three letters to divide the world into five major climate regions (A, B, C, D, and E) based on average annual precipitation, average monthly precipitation, and average monthly temperature. Each category is further divided into sub-categories based on temperature and precipitation. While the Koppen system does not take such things as temperature extremes, average cloud cover, number of days with sunshine, or wind into account, it is a good representation of our earth’s climate.

loss to follow-up (LTFU)

Patients who at one point were actively participating in disease treatment or clinical research, but have become lost either by error or by becoming unreachable at the point of follow-up.

LTFU

See loss to follow-up.

ordinary differential equation (ODE)

A differential equation containing one or more functions of one independent variable and its derivatives.

prevalence

The rate of all cases of a disease during a specified time period. This is a measure of how widespread a disease is.

recovered

Individual who is either no longer infectious, or “removed” from the population.

reproductive number

In a fully susceptible population, the basic reproductive number R0 is the number of secondary infections generated by the first infectious individual over the course of the infectious period. R0=S*L* \(\beta\) (where S = the number of susceptible hosts, L = length of infection, and \(\beta\) = transmissibility). When R0> 1, disease will spread. It is essentially a measure of the expected or average outcome of transmission. The effective reproductive number takes into account non-susceptible individuals. This is the threshold parameter used to determine whether or not an epidemic will occur, and determines:

  • The initial rate of increase of an epidemic (the exponential growth phase).

  • The final size of an epidemic (what fraction of susceptibles will be infected).

  • The endemic equilibrium fraction of susceptibles in a population (1/ R0).

  • The critical vaccination threshold, which is equal to 1-(1/ R0), and determines the number of people that must be vaccinated to prevent the spread of a pathogen.

routine immunization (RI)

The standard practice of vaccinating the majority of susceptible people in a population against vaccine-preventable diseases.

SEIR model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, exposed, infectious, and recovered.

SEIRS model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, exposed, infectious, recovered, and susceptible.

SI model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible and infectious.

simulation burn-in

A modeling concept in which a simulation runs for a period of time before reaching a steady state and the output during that period is not used for predictions. This concept is borrowed from the electronics industry where the first items produced by a manufacturing process are discarded.

SIR model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, and recovered.

SIRS model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, recovered, and susceptible.

SIS model

A generic epidemiological model that provides a simplified means of describing the transmission of an infectious disease through individuals where those individuals can pass through the following five states: susceptible, infectious, and susceptible.

stochastic

Characterized by having a random probability distribution that may be analyzed statistically but not predicted precisely.

stochastic die-out

When an disease outbreak ends, despite having an effective R0 above 1, due to randomness. A deterministic model cannot estimate the probability of stochastic die- out, but a stochastic model can.

subpatent

When an individual is infected but asymptomatic, so the infection is not readily detectable.

superinfection

The simultaneous infection with multiple strains of the same pathogen.

supplemental immunization activity (SIA)

In contrast to routine immunization (RI), SIAs are large-scale operations with a goal of delivering vaccines to every household.

susceptible

Individual who is able to become infected.

transmissibility (\(\beta\))

Also known as the effective contact rate, is the product of the contact rate and the probability of transmission per contact.

virulence

The capacity of a pathogen to produce disease. It is proportional to parasitemia, or the number of circulating copies of the pathogen in the host. The higher the virulence (given contact between S and I individuals), the more likely transmission is to occur. However, higher virulence means contact may be less likely as infected hosts show more symptoms of the disease. There is a trade-off that occurs between high transmissibility and disease- induced mortality.

WAIFW matrix

A matrix of values that describes the rate of transmission between different population groups. WAIFW is an abbreviation for Who Acquires Infection From Whom.

Weibull distribution

A probability distribution often used in EMOD and that requires both a shape parameter and a scale parameter. The shape parameter governs the shape of the density function. When the shape parameter is equal to 1, it is an exponential distribution. For shape parameters above 1, it forms a unimodal (hump-shaped) density function. As the shape parameter becomes large, the function forms a sharp peak. The inverse of the shape parameter is sometimes referred to here as the “heterogeneity” of the distribution (heterogeneity = 1/shape), because it can be helpful to think about the degree of heterogeneity of draws from the distribution, especially for hump-shaped functions with heterogeneity values between 0 and 1 (i.e., shape parameters greater than 1). The scale parameter shifts the distribution from left to right. When heterogeneity is small (i.e., the shape parameter is large), the scale parameter sets the location of the sharp peak.

EMOD software terms

agent-based model

A type of simulation that models the actions and interactions of autonomous agents (both individual and collective entities such as organizations or groups).

Boost

Free, peer-reviewed, portable C++ source libraries aimed at a wide range of uses including parallel processing applications (Boost.MPI). For more information, please see the Boost website, http://www.boost.org.

boxcar function

A mathematical function that is equal to zero over the entire real line except for a single interval where it is equal to a constant.

campaign

A collection of events that use interventions to modify a simulation.

campaign event

A JSON object that determines when and where an intervention is distributed during a campaign.

campaign file

A JSON (JavaScript Object Notation) formatted file that contains the parameters that specify the distribution instructions for all interventions used in a campaign, such as diagnostic tests, the target demographic, and the timing and cost of interventions. The location of this file is specified in the configuration file with the Campaign_Filename parameter. Typically, the file name is campaign.json.

channel

A property of the simulation (for example, “Parasite Prevalence”) that is accumulated once per simulated time step and written to file, typically as an array of the accumulated values.

class factory

A function that instantiate objects at run-time and use information from JSON-based configuration information in the creation of these objects.

configuration file

A JSON (JavaScript Object Notation) formatted file that contains the parameters sufficient for initiating a simulation. It controls many different aspects of the simulation, such as population size, disease dynamics, and length of the simulation. Typically, the file name is config.json.

core

In computing, a core refers to an independent central processing unit (CPU) in the computer. Multi-core computers have more than one CPU. However, through technologies such as Hyper- Threading Technology (HTT or HT), a single physical core can actually act like two virtual or logical cores, and appear to the operating system as two processors.

demographics file

A JSON (JavaScript Object Notation) formatted file that contains the parameters that specify the demographics of a population, such as age distribution, risk, birthrate, and more. IDM provides demographics files for many geographic regions. This file is typically named <region>_demographics.json.

destination node

The node an individual or group is traveling to for each leg of the migration. The destination updates as individuals move between nodes.

disease-specific build

A build of the EMOD executable (Eradication.exe) built using SCons without any dynamic link libraries (DLLs).

Microsoft’s implementation of a shared library, separate from the EMOD executable (Eradication.exe), that can be dynamically loaded (and unloaded when unneeded) at runtime. This loading can be explicit or implicit.

EMODule

A modular component of EMOD that are consumed and used by the EMOD executable (Eradication.exe). Under Windows, a EMODule is implemented as a dynamic link library (DLL) and, under CentOS, EMODules are currently not supported. EMODules are primarily custom reporters.

Epidemiological MODeling software (EMOD)

The modeling software from the Institute for Disease Modeling (IDM) for disease researchers and developers to investigate disease dynamics, and to assist in combating a host of infectious diseases. You may see this referred to as Disease Transmission Kernel (DTK) in the source code.

Eradication.exe

Typical (default) name for the EMOD executable (Eradication.exe), whether built using monolithic build or modular (EMODule-enabled) build.

event coordinator

A JSON object that determines who will receive a particular intervention during a campaign.

flattened file

A single campaign or configuration file created by combining a default file with one or more overlay files. Multiple files must be flattened prior to running a simulation. Configuration files are flattened to a single-depth JSON file without nesting, the format required for consumption by the EMOD executable (Eradication.exe). Separating the parameters into multiple files is primarily used for testing and experimentation.

Heterogeneous Intra-Node Transmission (HINT)

A feature for modeling person-to-person transmission of diseases in heterogeneous population segments within a node for generic simulations.

high-performance computing (HPC)

The use of parallel processing for running advanced applications efficiently, reliably, and quickly.

home node

The node where the individuals reside; each individual has a single home node.

individual properties

Labels that can be applied to individuals within a simulation and used to configure heterogeneous transmission, target interventions, and move individuals through a health care cascade.

input files

The JSON and binary files used as inputs to an EMOD simulation. The primary input files are the JSON-formatted configuration, demographics, and campaign files. They may also include the binary files for migration, climate, population serialization, or load- balancing.

inset chart

The default JSON output report for EMOD that includes multiple channels that contain data at each time step of the simulation. These channels include number of new infections, prevalence, number of recovered, and more.

intervention

An object aimed at reducing the spread of a disease that is distributed either to an individual; such as a vaccine, drug, or bednet; or to a node; such as a larvicide. Additionally, initial disease outbreaks and intermediate interventions that schedule another intervention are implemented as interventions in the campaign file.

JSON

See JavaSCript Object Notation.

JSON (JavaScript Object Notation)

A human-readable, open standard, text-based file format for data interchange. It is typically used to represent simple data structures and associative arrays, and is language-independent. For more information, see https://www.json.org.

Keyhole Markup Language (KML)

A file format used to display geographic data in an Earth browser, for example, Google Maps. The format uses an XML-based structure (tag-based structure with nested elements and attributes). Tags are case-sensitive.

A method for the linker to optimize code (for size and/or speed) after compilation has occurred. The compiled code is turned not into actual code, but instead into an intermediate language form (IL, but not to be confused with .NET IL which has a different purpose). The LTCG then, unlike the compiler, can see the whole body of code in all object files and be able to optimize the result more effectively.

Message Passing Interface (MPI)

An interface used to pass information between computing cores in parallel simulations. One example is the migration of individuals from one geographic location to another within EMOD simulations.

microsolver

A type of “miniature model” that operates within the framework of EMOD to compute a particular set of parameters. Each microsolver, in effect, is creating a microsimulation in order to accurately capture the dynamics of that particular aspect of the model.

monolithic build

A single EMOD executable (Eradication.exe) with no DLLs that includes all components as part of Eradication.exe itself. You can still use EMODules with the monolithic build; for example, a custom reporter is a common type of EMODule. View the documentation on EMODules and emodules_map.json for more information about creation and use of EMODules.

Monte Carlo method

A class of algorithms using repeated random sampling to obtain numerical results. Monte Carlo simulations create probability distributions for possible outcomes, which provides a more realistic way of describing uncertainty.

node

A grid size that is used for modeling geographies. Within EMOD, a node is a geographic region containing simulated individuals. Individuals migrate between nodes either temporarily or permanently using mobility patterns driven by local, regional, and long- distance transportation.

node properties

Labels that can be applied to nodes within a simulation and used to target interventions based on geography.

node-targeted intervention

An intervention that is distributed to a geographical node rather than to a single individual. One example is larvicides, which affect all mosquitoes living and feeding within a given node.

nodes

See node.

origin node

The “starting point” node fo reach leg of a migration trip. The origin updates as individuals move between nodes.

output report

A file that is the output from an EMOD simulation. Output reports are in JSON, CSV, or binary file format. You must pass the data from an output report to graphing software if you want to visualize the output of a simulation.

overlay file

An additional configuration, campaign, or demographic file that overrides the default parameter values in the primary file. Separating the parameters into multiple files is primarily used for testing a nd experimentation. In the case of configuration and campaign files, the files can use an arbitrary hierarchical structure to organize parameters into logical groups. Configuration and campaign files must be flattened into a single file before running a simulation.

preview

Software that undergoes a shorter testing cycle in order to make it available more quickly. Previews may contain software defects that could result in unexpected behavior. Use EMOD previews at your own discretion.

regression test

A test to verify that existing EMOD functionality works with new updates, located in the Regression subdirectory of the EMOD source code repository. Directory names of each subdirectory in Regression describe the main regression attributes, for example, “1_Generic_Seattle_MultiNode”. Also can refer to the process of regression testing of software.

release

Software that includes new functionality, scientific tutorials leveraging new or existing functionality, and/or bug fixes that have been thoroughly tested so that any defects have been fixed before release. EMOD releases undergo full regression testing.

reporter

Functionality that extracts simulation data, aggregates it, and saves it as an output report. EMOD provides several built-in reporters for outputting data from simulations and you also have the ability to create a custom reporter.

scenario

A collection of input files that describes a real-world example of a disease outbreak and interventions. Many scenarios are included with EMOD source installations or are available to download at EMOD scenarios to learn more about epidemiology and disease modeling.

schema

A text or JSON file that can be generated from the EMOD executable (Eradication.exe) that defines all configuration and campaign parameters.

simulation

An execution of the EMOD software using an associated set of input files.

simulation type

The disease or disease class to model.

EMOD supports the following simulation types for modeling a variety of diseases:

  • Generic disease (GENERIC_SIM), which can be used for modeling a variety of diseases such as influenza or measles

  • Vector-borne diseases (VECTOR_SIM), which can be used for modeling vector-borne diseases such as dengue

  • Malaria (MALARIA_SIM), which adds features specific to malaria biology and treatment

  • Tuberculosis with HIV coinfection (TBHIV_SIM), which can be used for modeling TB transmission, with the option to add HIV coinfection as a contributing factor

  • Sexually transmitted infections (STI_SIM), which adds features for sexual relationship networks

  • HIV (HIV_SIM), which adds features specific to HIV biology and treatment

  • Environmental transmission (ENVIRONMENTAL_SIM), which adds features for diseases transmitted through contaminated food or water

  • Typhoid (TYPHOID_SIM), which adds features specific to typhoid biology and treatment

solvers

Solvers are used to find computational solutions to problems. In simulations, they can be used, for example, to determine the time of the next simulation step, or to compute the states of a model at particular time steps.

Standard Template Library (STL)

A library that contains a set of common C++ classes (including generic algorithms and data structures) that are independent of container and implemented as templates, which enables compile-time polymorphism (often more efficient than run-time polymorphism). For more information and discussion of STL, see Wikipedia - Standard Template Library for more information.

state transition event

A change in state (e.g. healthy to infected, undiagnosed to positive diagnosis, or birth) that may trigger a subsequent action, often an intervention. “Campaign events” should not be confused with state transition events.

time step

A discrete number of hours or days in which the “simulation states” of all “simulation objects” (interventions, infections, immune systems, or individuals) are updated in a simulation. Each time step will complete processing before launching the next one. For example, a time step would process the migration data for populations moving between nodes via rail, airline, and road. The migration of individuals between nodes is the last step of the time step after updating states.

tutorial

A set of instructions in the documentation to learn more about epidemiology and disease modeling. Tutorials are based on real-world scenarios and demonstrate the mechanics of the the model. Each tutorial consists of one or more scenarios.

working directory

The directory that contains the configuration and campaign files for a simulation. You must be in this directory when you invoke Eradication.exe at the command line to run a simulation.

STI terms

coital dilution

The reduction in the number of sexual acts per partner when an additional, concurrent partner is added. Concurrency is defined as having two or more sexual partnerships overlapping in time.

mother-to-child transmission (MTCT)

The passage of a pathogen from mother to child, either from mother to embryo, fetus, or child during childbirth or through breastfeeding.

pair formation algorithm (PFA)

The method by which EMOD balances the “supply and demand” of partners and dynamically adjusts the rates of relationship formation in each demographic category to produce a constant mixing pattern, even with demographic changes in the population.

vertical transmission

The transmission of a pathogen across generations. This transmission mode is known as mother-to-child transmission, where the mother passes the pathogen to the embryo, fetus, or baby during pregnancy or childbirth.

HIV terms

apoptosis

Programmed cell death.

ART

Anti-retroviral therapy, a combination of anti-retroviral drugs that reduce the viral load, the amount of HIV virus in the bloodstream, to prevent AIDS symptoms and HIV transmission.

capsid

A protein shell of a virus, which encloses its genetic material.

CD4 cells

Immune cells with the CD4 glycoprotein on the cell surface. Often this term is used to refer specifically to CD4+ T helper cells, which are white blood cells that send signals to other immune cells that fight infection. Depleted CD4+ T helper cells caused by untreated HIV infection can make people vulnerable to a wide range of infections.

cell-mediated immunity

An immune response that involves the activation of phagocytes, antigen-specific T-lymphocytes, and the release of cytokines in response to an antigen. It does not involve antibodies.

dendritic cell

Immune cells that present antigens on their cell surface to the T helper cells, functioning as part of the signaling system between the innate and the adaptive immune responses.

entry inhibitors

Drugs such as enfuvirtide, maraviroc. These medications interfere with the processes of binding, fusion, and entry of virions into human cells.

glycoproteins

Proteins with an attached carbohydrate. Glycoproteins located in cellular membranes have important roles in cellular communication. They can function as receptors, chemical markers, attachment sites, and other functions. Some examples of glycoproteins include molecules such as antibodies or of the major histocompatibility complex (which are expressed on the surface of T-cells as part of adaptive immune responses).

gp120

Glycoprotein 120 (gp120) and gp41 comprise the envelope spike complex, or envelop proteins, found on the surface of HIV virions. The complex is responsible for the attachment, fusion, and infection of host cells. Gp120 can show high genetic variation, making it difficult for human immune systems to target the virion. CP120 forms the “spike” portion of the complex, and is essential to viral entry into host cells as it contains CD4 receptor binding sites.

gp41

Glycoprotein 41 (gp41) and gp120 comprise the envelope spike complex, or envelop proteins, found on the surface of HIV virions. The complex is responsible for the attachment, fusion, and infection of host cells. Gp41 is less genetically variable than gp120, and is the portion of the complex embedded in the viral envelope. Gp41 is the portion of the complex responsible for fusion of the host cell to the virion.

helper T-cells

See CD4 cells.

integrase

An enzyme that enables the viral genetic material to be integrated (inserted) into the DNA of the host cell.

integrase inhibitors

Drugs such as dolutegravir, raltegravir. These medications block the action of integrase, and enzyme that functions to insert the viral genome into the DNA of the host cell.

lentivirus

A subgroup of retroviruses characterized by very long incubation periods. These viruses are responsible for chronic and deadly disease in mammals. In primates, these viruses target the immune system, specifically using CD4 proteins as their receptors. Lentiviruses can become endogenous (integrating their genome into the host germline genome) making the virus vertically transmissible.

nonnucleoside reverse transcriptase inhibitors (NNRTIs)

Drugs such as efavirenz, etravirine, nevirapine. Like NRTIs, NNRTIs also work by inhibiting the process of reverse transcriptase. However, they are not nucleotide analogs and do not bind to the DNA strand; they function by non-competitive inhibition.

nucleoside reverse transcriptase inhibitors (NRTIs)

Also called nucleotide reverse transcriptase inhibitors. Drugs such as abacavir, emtricitabine, tenofovir. These medications work by inhibiting the process reverse transcriptase, converting RNA to DNA. NRTIs are analogs of the natural ATCG nucleotides used by reverse transcriptase, bt lack the 3’-OH group that is necessary for the next base to attach. Therefore, they competitively inhibit reverse transcriptase.

opportunistic infections

Infections that occur in individuals with weakened immune systems caused by microorganisms that are often harmless to healthy individuals. When HIV+ individuals contract opportunistic infections, they will be diagnosed with AIDS.

PEP

Post-exposure prophylaxis; taking ART after exposure to prevent infection with HIV.

PMTCT

Prevention of mother-to-child transmission. Programs and interventions with the goal of preventing the transmission of HIV from mother to child during pregnancy, childbirth, or breastfeeding. These programs rely on the use of antiretroviral medications to reduce the risk of transmission.

PrEP

Pre-exposure propylaxis. A daily pill that reduces the risk of HIV acquisition by up to 90%, and is comprised of nuecleoside reverse transcriptase inhibitors. Taken by individuals at very high risk of contracting HIV.

protease

An enzyme that performs proteolysis, or protein catabolism by hodrolysis of peptide bonds (which breaks proteins down into smaller peptide chains or into amino acids).

protease inhibitors

Drugs such as atazanavir, darunavir, ritonavir. These medications prevent viral replication by selectively binding to viral proteases and blocking proteolytic cleavage of the protein precursors necessary for the production of infectious viral particles.

proteases

See protease.

pyroptosis

A highly inflammatory form of programmed cell death that occurs most frequently when cells are infected with intracellular pathogens.

retrovirus

A single-stranded positive-sense RNA virus that uses a DNA intermediate.

reverse transcriptase

An enzyme used to generate DNA from an RNA template.

ribonuclease

A type of enzyme that breaks down RNA into smaller components.

serodifferent

Also termed “serodiscorcant,” this refers to when one partner is HIV- and the other is HIV+.

viral load

The amount of virus in the blood, expressed as viral particles per mL.

virion

The complete, infective form of a virus outside of a host cell, with a core of RNA or DNA and a capsid. Also known as a viral particle.

EMOD source code installation

This section describes how to install the software needed to build the EMOD executable (Eradication.exe) or Eradication binary for Linux from the EMOD source code. This is necessary if you want to modify the source code to extend the capabilities of the model beyond what’s available with the latest EMOD release. For example, you may want to model a disease that isn’t currently supported in EMOD. You can build Eradication.exe from source code on computers running Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) or build the Eradication binary for Linux on computers running CentOS 7.1.

After building, you should run a single simulation to verify basic functionality. We recommend the 27_Vector_Sandbox scenario in the Regression directory, which is a simple five-year vector simulation with an indoor residual spraying (IRS) campaign in the third year, executed on a single-node geography that is based on Namawala, Tanzania. This simulation generally takes a few minutes to execute.

However, you can run a simulation using any of the subdirectories under Regression, which when used with the demographics and climate files provided by IDM, contain complete sets of files for EMOD simulations.

After that, we recommend running full regression tests to further verify that EMOD is behaving as expected and that none of the source code changes inadvertently changed the EMOD functionality. See Regression testing for more information.

The EMOD executable (Eradication.exe) is tested using Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit). Windows HPC Server is used for testing remote simulations on a high-performance computing (HPC) cluster and the other Windows operating systems are used to test local simulations.

The Eradication binary for Linux is tested and supported on a CentOS 7.1 virtual machine on Azure. It has also been successfully built and run on Ubuntu, SUSE, and Arch, but has not been tested and is not supported on those Linux distributions.

Install Windows prerequisites for EMOD source code

This section describes the software packages or utilities must be installed on computers running Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) to build the EMOD executable (Eradication.exe) from source code and run regression tests.

If additional software is needed for the prerequisite software due to your specific environment, the installer for the prerequisite software should provide instructions. For example, if Microsoft MPI v10 requires additional Visual C++ redistributable packages, the installer will display that information.

Note

IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.

Install prerequisites for running simulations

The following software packages are required to run simulations using Eradication.exe. If you already installed the pre-built Eradication.exe using the instructions in EMOD installation, you can skip this section.

  1. Install the Microsoft HPC Pack 2019 Client Utilities Redistributable Package (64-bit). See https://www.microsoft.com/en-us/download/details.aspx?id=101361 for instructions.

  2. Install the Microsoft MPI v10. See https://www.microsoft.com/en-us/download/details.aspx?id=100593 for instructions, being sure to run the MSMpiSetup.exe file.

  3. Install the Microsoft Visual C++ 2022 Redistributable (64-bit). See https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist for instructions.

Install prerequisites for compiling from source code

The following software packages are required to build Eradication.exe from EMOD source code on Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit).

Visual Studio

  1. Purchase a license from Microsoft or use an MSDN subscription to install Visual Studio 2022 (Professional, Premium, or Ultimate). Other versions of Visual Studio are not supported.

    While you can use a free copy of Visual Studio Community, IDM does not test on or support this version.

  2. Select Desktop development with C++ during installation.

Python

Python is required for building the disease-specific Eradication.exe and running Python scripts.

  1. In a web browser, go to https://www.python.org/downloads/release/python-399/ to install Python 3.9 64-bit.

  2. Scroll down and download one of the x86-64 bit installers (you may use the executable installer or the web-based installer.)

  3. Double-click the executable file and, in the installer window, select the Add Python 3.9 to PATH checkbox and click Customize installation.

  4. On the Optional Features window that opens, leave all default values selected and click Next. The Python package manager, pip, is used to install other Python packages.

  5. If you are running EMOD locally, IDM recommends that you select the Advanced Options window to customize the installation directory to “C:\Python39”.

    You may install Python in another location, but the Python plotting scripts included in the EMOD scenarios zip file assume that Python is installed directly under the C: drive. If you install it elsewhere, you may need to edit those scripts when using the scenarios to learn about EMOD functionality.

  6. Click Install. When installation is complete, click Close.

  7. To verify installation, open a Command Prompt window and type the following:

    python --version

  8. From Control Panel, select Advanced system settings, and then click Environment Variables.

    • To build the source code using Python 3.9 64-bit, add a new variable called IDM_PYTHON3X_PATH and set it to the directory where you installed Python 3.9 64-bit, and then click OK.

  9. Restart Visual Studio if it was open when you set the environment variables.

HPC SDK
Boost

  1. Go to https://sourceforge.net/projects/boost/files/boost/1.77.0/ and select one of the compressed files.

  2. Unpack the libraries to the location of your choice. If unpacking the files results duplicate folders with an extra level of nesting (for example, C://boost_1_77_0//boost_1_77_0), delete the extra folder.

  3. From Control Panel, select Advanced system settings, and then click Environment Variables.

  4. Add a new variable called IDM_BOOST_PATH and set it to the directory where you installed Boost, and then click OK.

  5. Restart Visual Studio if it was open when you set the environment variable.

(Optional) SCons

SCons is required for the building disease-specific Eradication.exe and is optional for the monolithic Eradication.exe that includes all simulation types.

  1. Open a Command Prompt window and enter the following:

    pip install wheel
pip install scons
Install prerequisites for running regression tests

The following plotting software is required for running regression tests, where graphs of model output are created both before and after source code changes are made to see if those changes created a discrepancy in the regression test output. For more information, see Regression testing.

NumPy

We recommended that you download some of the NumPy Python package from http://www.lfd.uci.edu/~gohlke/pythonlibs, a page compiled by Christoph Gohlke, University of California, Irvine. The libraries there include linear algebra packages that are not included by default with the standard Windows packages. They are compiled Windows binaries, including the 64-bit versions required by EMOD. The naming convention used lists the Python version after “cp”, for example “cp39-cp39m”, and the Windows bit version after “win”, for example “win_amd64”.

The NumPy package adds support for large, multi-dimensional arrays and matrices to Python.

  1. Go to http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy and select the WHL file for NumPy 1.22.1 (64-bit) that is compatible with Python 3.9 64-bit.

  2. Save the file to your Python installation directory.

  3. Open a Command Prompt window and navigate to the Python installation directory, then enter the following, substituting the name of the specific NumPy WHL file you downloaded:

    pip install numpy-1.x.x+mkl-cp39-cp39m-win_amd64.whl
Python packages

The Python packages dateutil, six, and pyparsing provide text parsing and datetime functionality.

Note

Be sure NumPy is installed before you install Matplotlib.

  1. Open a Command Prompt window and enter the following:

    pip install python-dateutil
pip install pyparsing
pip install matplotlib
pip install future
(Optional) R

The IDM test team uses R 4.1.2 (64-bit) for regression testing, but it is considered optional.

R is a free software environment for statistical computing and graphics.

(Optional) MATLAB

The IDM test team uses MATLAB R2021b and the MATLAB Statistics and Machine Learning Toolbox™ R2021b for regression testing, but they are both considered optional.

MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.

  1. Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2021b.

  2. If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2021b.

Install CentOS prerequisites for EMOD source code

This section describes the software packages or utilities must be installed on computers running CentOS 7.1 to build the Eradication binary for Linux from source code and run regression tests.

If additional software is needed for the prerequisite software due to your specific environment, the installer for the prerequisite software should provide instructions. For example, if Microsoft MPI v10 requires additional Visual C++ redistributable packages, the installer will display that information.

Note

IDM does not provide support or guarantees for any third-party software, even software that we recommend you install. Send feedback if you encounter any issues, but any support must come from the makers of those software packages and their user communities.

Install prerequisites for running simulations

The following software packages are required to run simulations using the Eradication binary for Linux. If you already installed the pre-built Eradication.exe using the instructions in EMOD installation, you can skip this section.

Before you begin, you must have the following:

  • sudo privileges to install packages

  • 15 GB free in your home directory (if you install the EMOD source code and input files)

  • An Internet connection

  1. On GitHub on the EMOD releases page, download and run the PrepareLinuxEnvironment.sh script.

    Respond to the prompts for information while the script is running.

    1. Set the EMOD_ROOT environment variable to the path to the EMOD source path:

      EMOD_ROOT=~/IDM/EMOD

    2. Include Scripts and . in the path:

      export PATH=$PATH:.:$EMOD_ROOT/Scripts

    3. If you want to run simulations in the same session that you updated EMOD_ROOT and the Scripts path, reload the .bashrc file using source .bashrc.

Install prerequisites for compiling from source code

For CentOS 7.1, all prerequisites for building the Eradication binary for Linux are installed by the setup script described above. However, if you originally installed EMOD without including the source code and input files that are optional for running simulations using a pre-built Eradication binary for Linux, rerun the script and install those.

Install prerequisites for running regression tests

The setup script includes most plotting software required for running regression tests, where graphs of model output are created both before and after source code changes are made to see if those changes created a discrepancy in the regression test output. For more information, see Regression testing. You may want to install R or MATLAB, but both are optional.

We recommended that you download some of the NumPy Python package from http://www.lfd.uci.edu/~gohlke/pythonlibs, a page compiled by Christoph Gohlke, University of California, Irvine. The libraries there include linear algebra packages that are not included by default with the standard Windows packages. They are compiled Windows binaries, including the 64-bit versions required by EMOD. The naming convention used lists the Python version after “cp”, for example “cp39-cp39m”, and the Windows bit version after “win”, for example “win_amd64”.

(Optional) R

The IDM test team uses R 4.1.2 (64-bit) for regression testing, but it is considered optional.

R is a free software environment for statistical computing and graphics.

(Optional) MATLAB

The IDM test team uses MATLAB R2021b and the MATLAB Statistics and Machine Learning Toolbox™ R2021b for regression testing, but they are both considered optional.

MATLAB is a high-level language and interactive environment for numerical computation, visualization, and programming. The MATLAB Statistics and Machine Learning Toolbox™ provides functions and applications to describe, analyze and model data using statistics and machine learning algorithms.

  1. Go to http://www.mathworks.com/products/matlab/ and install MATLAB R2021b.

  2. If desired, go to https://www.mathworks.com/products/statistics.html and install the MATLAB Statistics and Machine Learning Toolbox™ R2021b.

Download the EMOD source code

The EMOD source code is available on GitHub. The EMOD source includes the source code, Visual Studio solution, sample configuration files, as well as regression test and other files needed to fully build and test the EMOD executable (Eradication.exe).

You can have multiple versions of the EMOD source code in separate directories on your local computer. For example, you might want to download a new release of EMOD but also keep a previous release of the source. In the following examples, the source code is downloaded to the directory EMOD at C:/IDM, but you can save to any location you want.

You can use any Git client of your choice to clone the EMOD repository from from GitHub. These instructions walk through the process using Git GUI or Git Bash if you are new to using Git.

Install Git GUI and Git Bash

To install Git GUI and Git Bash, download a 64-bit version of Git from https://git-scm.com/download. On the Select Components installer window, you can select one or both of Git GUI Here for a GUI or Git Bash Here for a command window.

Use Git GUI to download the EMOD source

  1. Launch the Git GUI application and click Clone Existing Repository.

  2. From the Clone Existing Repository window:

    1. In Source Location, enter https://github.com/InstituteforDiseaseModeling/EMOD

    2. In Target Directory, enter the location and target directory name: C:/IDM/EMOD

    3. Click Clone. Git GUI will create the directory and download the source code.

  3. Close the Git GUI window when the download completes.

Use Git Bash to download the EMOD source

Note

For a list of the Git Bash commands, type git help git or type git help <command> for information about a specific command.

  1. Launch the Git Bash application. From the command line:

    1. Navigate to the location where you want to save your copy of the EMOD source code:

      cd C:/IDM

    2. Clone the repository from GitHub:

      git clone https://github.com/InstituteforDiseaseModeling/EMOD

Git Bash will copy the EMOD source to a directory named EMOD by default.

Verify that all directories on https://github.com/InstituteforDiseaseModeling/EMOD are now reflected on your local clone of the repository.

(Optional) Download input files

IDM provides input files that describe the demographics, migration patterns, and climate of many different locations across the world. You can download these files from the EMOD-InputData repository, which uses large file storage (LFS) to manage the binaries and large JSON (JavaScript Object Notation) files. A standard Git clone of the repository will only retrieve the metadata for these files managed with LFS. To retrieve the actual data, follow the steps below.

  1. Install the Git LFS plugin, if it is not already installed.

    • For Windows users, download the plugin from https://git-lfs.github.com.

    • For CentOS users, the plugin is included with the PrepareLinuxEnvironment.sh script.

  2. Using a Git client or Command Prompt window, clone the input data repository to retrieve the metadata:

    git clone https://github.com/InstituteforDiseaseModeling/EMOD-InputData.git

  3. Navigate to the directory where you downloaded the metadata for the input files.

  4. Download the actual data on your local machine:

    git lfs fetch

  5. Replace the metadata in the files with the actual data:

    git lfs checkout

Build EMOD from source code

You can build the Eradication.exe for Windows 10, Windows Server 12, and Windows HPC Server 12 (64-bit) using Microsoft Visual Studio or SCons. You can build the Eradication binary for Linux for CentOS 7.1 using SCons.

If you want full debugging support, you must build using Visual Studio. However, Visual Studio is only capable of a monolithic build that includes all supported simulation types.

EMOD supports the following simulation types for modeling a variety of diseases:

  • Generic disease (GENERIC_SIM), which can be used for modeling a variety of diseases such as influenza or measles

  • Vector-borne diseases (VECTOR_SIM), which can be used for modeling vector-borne diseases such as dengue

  • Malaria (MALARIA_SIM), which adds features specific to malaria biology and treatment

  • Tuberculosis with HIV coinfection (TBHIV_SIM), which can be used for modeling TB transmission, with the option to add HIV coinfection as a contributing factor

  • Sexually transmitted infections (STI_SIM), which adds features for sexual relationship networks

  • HIV (HIV_SIM), which adds features specific to HIV biology and treatment

  • Environmental transmission (ENVIRONMENTAL_SIM), which adds features for diseases transmitted through contaminated food or water

  • Typhoid (TYPHOID_SIM), which adds features specific to typhoid biology and treatment

If you want to create a disease-specific build, you must build using SCons. However, SCons builds build only the release version without extensive debugging information.

Build a monolithic Eradication.exe with Visual Studio

You can use the Microsoft Visual Studio solution file in the EMOD source code repository to build the monolithic version of the EMOD executable (Eradication.exe), which can be either a release or debug build. Visual Studio 2022 (Professional, Premium, or Ultimate) is the currently supported version.

Warning

Visual Studio creates a debug build by default. However, you must use a release build to commission simulations to COmputational Modeling Platform Service (COMPS); attempting to use a debug build will result in an error.

  1. In Visual Studio, navigate to the directory where the EMOD repository is cloned and open the EradicationKernel solution.

  2. If prompted to upgrade the C++ toolset used, do so.

  3. From the Solution Configurations ribbon, select Debug or Release.

  4. On the Build menu, select Build Solution.

Eradication.exe will be in a subdirectory of the Eradication directory.

Build Eradication.exe or Eradication binary for Linux with SCons

SCons is a software construction tool that is an alternative to the well-known “Make” build tool. It is implemented in Python and the SCons configuration files, SConstruct and SConscript, are executed as Python scripts. This allows for greater flexibility and extensibility, such as the creation of custom SCons abilities just for EMOD. For more information on Scons, see www.scons.org. SCons 3.0.1 is the currently supported version.

Warning

EMOD will not build if you use the --Debug flag. To build a debug version, you must use Visual Studio.

  1. Open a Command Prompt window.

  2. Go to the directory where EMOD is installed:

    cd C:\IDM\EMOD

  3. Run the following command to build Eradication.exe:

    • For a monolithic build:

      scons --Release

    • For a disease-specific build, specify one of the supported disease types using the --Disease flag:

      scons --Release --Disease=Vector

  4. The executable will be placed, by default, in the subdirectory build\x64\Release\Eradication\ of your local EMOD source.

Additionally, you can parallelize the build process with the --jobs flag. This flag indicates the number of jobs that can be run at the same time (a single core can only run one job at a time). For example:

scons --Release --Disease=Vector --jobs=4

Getting started with building EMOD source code from CentOS Docker images

The EMOD source code can be built from the following CentOS Docker images available on JFrog Artifactory:

Image name

Repository path

Description

dtk-build

docker-production.packages.idmod.org/idm/centos:dtk-build

EMOD source code to build and run the EMOD executable (Eradication.exe).

dtk-runtime

docker-production.packages.idmod.org/idm/centos:dtk-runtime

EMOD files needed for running a pre-built CentOS EMOD executable (Eradication.exe).

dtk-sfts

docker-production.packages.idmod.org/idm/centos:dtk-sfts

EMOD source code to build test and run the EMOD executable (Eradication.exe).

You can build these images on Windows and Linux machines. The following steps were tested and documented from machines running Linux for CentOS 7.7 and Windows 10.

Prerequisites

  • privileges to install packages (sudo on Linux, admin on Windows)

  • An Internet connection

  • Git client

  • Docker client

To verify whether you have Git and Docker clients installed you can type the following at a command line prompt:

git --version
docker --version
Download and install prerequisites

Git version 1.8.3.1 and Docker CE version 19.03.3 were used for creating this documentation.

To download and install a Git client, see https://git-scm.com/download.

To download and install a Docker client for CentOS, see https://docs.docker.com/install/linux/docker-ce/centos/ To download and install a Docker client for Windows, see https://docs.docker.com/docker-for-windows/install/

Clone EMOD source code

To clone EMOD source code, type the following at a command line prompt:

git clone https://github.com/InstituteForDiseaseModeling/EMOD.git

The next steps are to run the Docker container and build the EMOD source code from the CentOS Docker images. If your host machine is running Linux, see Building EMOD source code from CentOS Docker images on Linux host machine. If your host machine is running Windows, see Building EMOD source code from CentOS Docker images on Windows host machine.

Building EMOD source code from CentOS Docker images on Linux host machine

These steps walk you through building the EMOD source code from CentOS Docker images on a Linux host machine running Linux for CentOS 7.7. Before following these steps you must meet the prerequisites in Getting started with building EMOD source code from CentOS Docker images. Although these steps are specific to the dtk-build image, you can use them for the other images by replacing “dtk-build” with the desired image name, such as “dtk-runtime” or “dtk-sfts”.

Download Docker image to Linux host machine

To download Docker image to your Linux host machine type the following at command line prompt:

docker pull docker-production.packages.idmod.org/idm/centos:dtk-build
Run Docker container from Linux host machine

To run Docker image from your Linux host machine type the following at command line prompt:

docker run -it --user `id -u $USER`:`id -g $USER` -v ~/EMOD:/EMOD docker-production.packages.idmod.org/idm/centos:dtk-build

To see additional information about the options used with the “docker run” command, type “docker run –help” at a command line prompt.

Upon completion you will then see a new command prompt for the Docker image, which in this example is as follows:

bash-4.2$

To then build the EMOD executable, Eradication.exe, move to the /EMOD directory:

cd /EMOD

This directories contains the necessary build script and files.

Build binary executable from Docker image running Linux CentOS 7.7 within Linux host machine

To build a binary executable you run the “scons” script. For more information about the build script options, type “scons –help” from within the /EMOD directory. In this example the Generic disease model is built. Type the following at command line prompt:

scons --Disease=Generic

Upon completion you will see the following line at the end of the build process:

scons: done building targets.

For more information, see Build EMOD from source code.

Verify EMOD binary executable

You can verify the successful build of the EMOD binary executable by typing the following at command line prompt:

/EMOD/build/x64/Release/Eradication/Eradication --version

You should see a response similar to the following:

Intellectual Ventures(R)/EMOD Disease Transmission Kernel 2.20.17.0
Built on Oct 25 2019 by luser from master(2d8a9f2) checked in on 2019-04-05 15:49:43 -0700
Supports sim_types: GENERIC.

You can then use this executable for running simulations. For more information, see Run a simulation using the command line.

Building EMOD source code from CentOS Docker images on Windows host machine

These steps walk you through building the EMOD source code from CentOS Docker images on a Windows host. Before following these steps you must meet the prerequisites in Getting started with building EMOD source code from CentOS Docker images. Although these steps are specific to the “dtk-build” image, you can use them for the other images by replacing “dtk-build” with the desired image name, such as “dtk-runtime” or “dtk-sfts”.

Download Docker image to Windows host machine

To download Docker image to your Windows host machine type the following at command line prompt:

docker pull docker-production.packages.idmod.org/idm/centos:dtk-build
Run Docker container from Windows host machine

To run Docker image from your Windows host machine type the following at command line prompt:

docker run -it -v C:\EMOD:/EMOD docker-production.packages.idmod.org/idm/centos:dtk-build

To see additional information about the options used with the “docker run” command, type “docker run –help” at a command line prompt.

Upon completion you will then see a new command prompt for the Docker image, which in this example is as follows:

[root@c23ffe9cb1fb /]#

To then build the EMOD executable, Eradication.exe, move to the /EMOD directory:

cd EMOD

This directories contains the necessary build script and files.

Build binary executable from Docker image running Linux CentOS 7.7 within Windows host machine

To build a binary executable you run the “scons” script. For more information about the build script options, type “scons –help” from within the EMOD directory. To specify a specific user name associated with the built binary executable, you can enter a specific user name by setting the “USER” environment variable that the build script uses. For example:

USER=johndoe

In this example the Generic disease model is built. Type the following at command line prompt:

scons --Disease=Generic

Upon completion you will see the following line at the end of the build process:

scons: done building targets.

For more information, see Build EMOD from source code.

Verify EMOD binary executable

You can verify the successful build of the EMOD binary executable by typing the following at command line prompt:

/EMOD/build/x64/Release/Eradication/Eradication --version

You should see a response similar to the following:

Intellectual Ventures(R)/EMOD Disease Transmission Kernel 2.20.17.0
Built on Oct 25 2019 by johndoe from master(2d8a9f2) checked in on 2019-04-05 15:49:43 -0700
Supports sim_types: GENERIC.

You can then use this executable for running simulations. For more information, see Run a simulation using the command line.

EMOD architecture

Epidemiological MODeling software (EMOD) is implemented in C++ and has two subsystems: the environment and the simulation controller. The environment contains the interfaces to the simulation controller subsystem and the external inputs and outputs. The simulation controller contains the epidemiological model (simulation and campaign management), and reporters that capture output data and create reports from a simulation. The following figure shows a high-level view of the system components of EMOD and how they are related to each other.

_images/ArchSystemComponents.png

EMOD system components

Warning

If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.

Environment subsystem

The environment subsystem provides access to global resources and most of the external input and output interfaces. Output reports are the only output not handled through the environment subsystem. It consists of a a singleton utility class, Environment. The environment subsystem consists of five logical components.

The following figure shows a high-level view of the system components of EMOD and how they are related to each other.

_images/ArchSystemComponents.png

EMOD system components

Input file readers

Provide small utility functions for reading in the input data, configuration, and campaign files. The actual parsing of the configuration and campaign files is done by the configuration manager component. The parsing of the input files is done by the model classes that consume that data, which are part of the simulation controller subsystem.

Configuration manager

Parses the configuration files, stores the parsed values for system-global configuration values, and provides a central container resource for the configuration as JSON to those classes that need to parse out the remaining configuration values locally for themselves. It retains the contents of the configuration file and the directories provided on the command line.

Error handler

Provides an application-level exception library and a centralized mechanism for handling all errors that occur during program execution. These errors are ultimately reported through the logging component.

Logger

Writes the output logs and errors. Output reports, such as time-series channel data reports, spatial channel data reports, progress and status summary, and custom reports, are handled by the simulation controller. For information and setting the logging level, see Set log levels.

Message Passing Interface (MPI)

EMOD is designed to support large-scale multi-node simulations by running multiple instances of EMOD in parallel across multiple compute nodes on a cluster. During initialization, geographical nodes are assigned to compute nodes. Individuals who migrate between geographical nodes that are not on the same compute node are migrated via a process of serialization, network I/O, and deserialization. The network communication is handled through a mixture of direct calls to the MPI library and use of Boost’s MPI facilities. This component provides the system-wide single interface to MPI, caching the number of tasks and rank of current process from the MPI environment.

Simulation controller subsystem

The simulation controller is the top-level structure for the epidemiological model. The controller’s capabilities are simple, running a single simulation in a single time direction at a constant rate. It exists to support future capabilities, such as running multiple simulations, pausing a simulation, or bootstrapping a simulation from an archived simulation. It contains two components: simulation and reporters.

The following figure shows a high-level view of the system components of EMOD and how they are related to each other.

_images/ArchSystemComponents.png

EMOD system components

Simulation

The simulation component contains core functionality that models the behavior of a disease without any interventions and extended functionality to include migration, climate, or other input data to create a more realistic simulation. Disease transmission may be more or less complex depending on the disease being modeled.

Campaign management

The simulation component also includes a campaign manager sub-component for including disease interventions in a simulation.

Reporter

The reporter component creates output reports for both simulation-wide aggregate reporting and spatial reporting.

Simulation core components

The simulation component contains core functionality that models the behavior of a disease without any interventions and extended functionality to include migration, climate, or other input data to create a more realistic simulation. Disease transmission may be more or less complex depending on the disease being modeled.

Warning

If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.

Content

Each generic EMOD simulation contains the following core base classes:

Simulation

Created by the simulation controller via a SimulationFactory with each run of EMOD.

Node

Corresponds to a geographic area. Each simulation maintains a collection of one or more nodes.

IndividualHuman

Represents a human being. Creates Susceptibility and Infection objects for the collection of individuals it maintains. The file name that defines this class is “Individual” and you may see it likewise shortened in diagrams.

Susceptibility

Manages an individual’s immunity.

Infection

Represents an individual’s infection with a disease.

For generic simulations, human-to-human transmission uses a homogeneous contagion pool for each node. Every individual in the node sheds disease into the pool and acquires disease from the pool. For specific disease simulations, transmission is heterogeneous and based on the disease biology.

The relationship between these classes is captured in the following figure.

_images/ArchSimulation.png

Simulation components

After the simulation is initialized, all objects in the simulation are updated at each time step, typically a single day. Each object implements a method Update that advances the state of the objects it contains, as follows:

  • Controller updates Simulation

  • Simulation updates Nodes

  • Node updates IndividualHuman

  • IndividualHuman updates Susceptibility, Infections, and InterventionsContainer

  • InterventionsContainer updates Interventions

Simulation

As a stochastic model, EMOD uses a random number seed for all simulations. The Simulation object has a data member (RNG) that is an object maintaining the state of the random number generator for the parent Simulation object. The only generator currently supported is pseudo-DES. The random seed is initialized from the configuration parameter Run_Number and from the process MPI rank. All child objects needing access to the RNG must be provided an appropriate (context) pointer by their owners.

The Simulation class contains the following methods:

Method

Description

Populate()

Initializes the simulation. The Populate method initializes the simulation using both the configuration file and the demographic files. Populate calls through to populateFromDemographics to enable the Simulation object to create one or many Node objects populated with IndividualHumans as dictated by the demographics file, in conjunction with the sampling mode and value dictated by the configuration file. If the configuration file indicates that a migration and a climate model are to be used, those input file are also read. Populate also initializes all Reporters.

Update()

Advances the state of nodes.
_images/ArchSimulationTree.png

Simulation object hierarchy

For multi-core parallelization, the demographics file is read in order on each process and identity of each node and is compared with a policy assigning nodes to processes embodied in objects implementing InitialLoadBalancingScheme. If the initial load balancing scheme allows a node for the current rank, the node is created via addNewNodeFromDemographics. After all nodes have been created and propagated, the NodeRankMaps are merged across all processes. See Load-balancing files for more information.

Node

Nodes are model abstractions that represent a population of individuals that interact in a way that does not depend on their geographic location. However, they represent a geographic location with latitude and longitude coordinates, climate information, migration links to other nodes, and miscellaneous demographic information. The Node is always the container for IndividualHumans and the contagion pool. The Node provides important capabilities for how IndividualHumans are created and managed. It can also contain a Climate object and Migration links if those features are enabled. The climate and migration settings are initialized based on the information in the input data files.

The Node class contains the following methods:

Method

Description

PopulateFromDemographics()

The entry point that invokes populateNewIndividualsFromDemographics(InitPop), which adds individuals to a simulation and initializes them. PopulateNewIndividualsFromBirth() operates similarly, but can use different distributions for demographics and initial infections.

Update()

Advances the state of individuals.

updateInfectivity()

The workhorse of the simulation, it processes the list of all individuals attached to the Node object and updates the force of infection data members in the contagion pool object. It calls a base class function updatePopulationStatistics, which processes all individuals, sets the counters for prevalence reporting, and calls IndividualHuman::GetInfectiousness for all IndividualHuman objects.

The code in GetInfectiousness governs the interaction of the IndividualHuman with the contagion pool object. The rest of the code in updateInfectivity processes the contagion beyond individual contributions. This can include decay of persisting contagion, vector population dynamics, seasonality, etc. This is also where the population-summed infectivity must be scaled by the population in the case of density-independent transmission.

updateVitalDynamics()

Manages community level vital dynamics, primarily births, since deaths occur at the individual level.

By default, an IndividualHuman object is created, tracked, and updated for every person within a node. To reduce memory usage and processing time, you may want to sample such that each IndividualHuman object represents multiple people. There are several different sampling strategies implemented, with different strategies better suited for different simulations. See Sampling for more information.

If migration is enabled, at the end of the Node update, the Node moves all migrating individuals to a separate migration queue for processing. Once the full simulation time step is completed, all migrating individuals are moved from the migration queue and added to their destination nodes.

IndividualHuman

The IndividualHuman class corresponds to human beings within the simulation. Individuals are always contained by a Node object. Each IndividualHuman object may represent one or more human beings, depending on the sampling strategy and value chosen.

The IndividualHuman class contains components for susceptibility, infection, and interventions. Infection and Susceptibility cooperate to represent the detailed dynamics of infection and immune mechanisms. Every IndividualHuman contains a Susceptibility object that represents the state of the immune system over time. Only an infected IndividualHuman contains an Infection object, and may contain multiple Infection objects.. Susceptibility is passed to initialize the infection immunology in Infection::InitInfectionImmunology(). The state of an individual’s susceptibility and infection are updated with Update() methods. Disease-specific models have additional derived classes with properties and methods to represent specifics of the disease biology.

The InterventionsContainer is the mediating structure for how interventions interrupt disease transmission or progression. Campaign distribution results in an Intervention object being added to an individual’s InterventionsContainer, where it remains unless and until it is removed. When an IndividualHuman calls Update(), the InterventionsContainer is updated and its effects are applied to the IndividualHuman. These effects are used in the individual, infection, and susceptibility update operations. If migration is enabled, at the end of each individual’s update step EMOD checks if the individual is scheduled for migration (IndividualHuman::CheckForMigration()), setting a flag accordingly.

The IndividualHuman class contains the following methods:

Method

Description

Update()

Advances the state of both the infection and the immune system and then registers any necessary changes in an individual’s state resulting from those dynamics (that is, death, paralysis, or clearance). It also updates intrinsic vital dynamics, intervention effects, migration, and exposure to infectivity of the appropriate social network.

ExposeToInfectivity()

Passes the IndividualHuman to the ExposeIndividual() function if it is exposed to infectivity at a time step.

UpdateInfectiousness()

Advances the quantity of contagion deposited to the contagion pool by an IndividualHuman at each time step of their infectious period. This is explained in more detail below.
Disease transmission

Transmission of disease is mediated through a pool mechanism which tracks abstract quantities of contagion. The pool mediates individual acquisition and transmission of infections as well as external processes that modify the infectivity dynamics external to individuals. The pool provides basic mechanisms for depositing, decaying, and querying quantities of contagion which are associated with a specific StrainIdentity. The pool internally manages a separate ContagionPopulation for each possible antigen identity. ContagionPopulations have further structure and manage an array of contagion quantities for each substrain identity.

Each IndividualHuman has a sampling weight \(W_i\) and a total infectiousness \(X_i\), the rate at which contacts with the infectious individual become infected. This rate can be modified by transmission-reducing immunity or heterogeneous contact rates, which are gathered in \(Y_{i,transmit}\), and the transmission-reducing effects of interventions, such as transmission- blocking vaccines in the factor \(Z_{i,transmit}\). The sampling weight \(W_i\) is not included in the probability of acquiring a new infection. Sample particles are simulated as single individuals, their weighting \(W_i\) is used to determine their effects upon the rest of the simulation.The total infectiousness \(T\) of the local human population is then calculated as:

\[T = \sum_iW_iX_iY_{i,transmit}Z_{i,transmit}\]

For simulation of population density-independent transmission, individual infectiousness \(X_i\) includes the average contact rate of the infectious individual, so this total infectiousness is divided by the population \(P\) to get the force of infection \(FI=\frac{T}{P}\) for each individual in the population. The base rate of acquisition of new infections per person is then \(FI\), which can be modified for each individual \(I\) by their characteristics \(Y_{i,acquire}\) and interventions \(Z_{i,acquire}\). Over a time step \(\Delta t\), the probability of an individual acquiring a new infection is then:

\[P_{I,i} = 1- \text{exp}(-F_IY_{i,acquire}Z_{i,acquire}\Delta t)\]

A new infection receives an incubation period and infectious period from the input configuration (a constant at present, but possibly from specified distributions in the future) and a counter tracks the full latency, which is possible when simulating individual particles. After the incubation period, the counter for the infectious period begins, during which time the infection contributes to the individual’s infectiousness \(X_i\).

Campaign management

Campaigns are structured into campaign events that determine when, where, and to whom the intervention will be distributed and interventions that determine what is distributed, for example vaccines or other treatments. This section describes the software architecture used for managing campaigns.

Campaigns can be very simple, such as a single intervention with fixed parameters at a point in time, or a complex, adaptive, repetitive, and responsive combination of interventions. A Campaign is a collection of events that modify a simulation. An Event is a distribution within a campaign, and an Intervention is an item that is given out, such as a vaccine, a drug or a bednet.

_images/ArchCampaignManagement.png

Warning

If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.

Campaign events

A campaign event triggers the campaign management system to evaluate when, where, and to whom the intervention will be distributed. This section describes the SimulationEventContext, CampaignEvent, NodeSet, and EventCoordinator classes used to manage this process.

For more information on setting up campaign files, see Creating campaigns.

SimulationEventContext

The Simulation class has a nested helper class called SimulationEventContextHost, referred to as SimulationEventContext. It serves as the interface to, or manager of, CampaignEvents for the Simulation class.

Incoming: The Simulation to SimulationEventContext interface contains the following methods:

Method

Description

LoadCampaignFromFile()

Loads the campaign file during simulation initialization (t=0).

RegisterEventCoordinator()

Registers new event coordinators. Also used by CampaignEvent during activation to notify the SimulationEventContext of a new active EventCoordinator.

Update()

Advances the state at each time step.

VisitNodes()

Called from CampaignEvent during its activation. CampaignEvent is not a Node container, so it needs to communicate with the Simulation class to do anything with nodes.

Outgoing: The SimulationEventContext communicates with CampaignEvents and EventCoordinators, which are described below.

CampaignEvent

The CampaignEvent class exists primarily as an initialization-time, minimal intelligence container with a 1-to-1 mapping for CampaignEvents found in the JSON campaign file. They do not do much in the way of run-time campaign distribution or control.

Incoming: The public interface for CampaignEvent contains the following methods:

Method

Description

CreateInstance()

For each campaign event that the SimulationEventContext finds in the campaign file, it creates a corresponding CampaignEvent instance via CampaignEventFactory. The nested JSON elements in a campaign event are stored as an opaque (that is, unparsed) JSON object known as Event_Coordinator_Config. Immediate parameters like Start_Day are parsed out of the JSON and stored in explicit variables in the CampaignEvent class.

Dispatch()

In its steady-state, the SimulationEventContext checks the start day for all existing CampaignEvents and invokes this method to when the time step matches the start day.

Outgoing: The CampaignEvent communicates with two other classes: NodeSet and EventCoordinator.

NodeSet

The NodeSet class parses the Nodeset_Config and helps the EventCoordinator determine if a given node is included in a particular intervention distribution. It can be as simple as NodeSetAll, which includes all nodes, or something much more involved. Usual cases include NodeSetPolygon and NodeSetCommunityList.

Incoming: The public interface for NodeSet contains the following methods:

Method

Description

Contains()

The caller passes a Node via the INodeEventContext interface and gets back a Boolean. The NodeSet class completely encapsulates whatever logic is used to evaluate node membership.
EventCoordinator

EventCoordinator is a base type that contains most of the functionality in the event distribution mechanism. There are two actual EventCoordinator classes implemented, but you can new implementations easily by creating a new EventCoordinator class.

Incoming: There are four classes or class groups that make calls into EventCoordinator:

  • CampaignEvents, which create and activate them.

  • The SimulationEventContext that invokes their steady-state methods.

  • Nodes (via the NodeEventContext helper class)

  • Interventions, which get EventCoordinator-level configuration data needed for intervention execution.

The public interface for EventCoordinator contains the following methods:

Method

Description

AddNode()

Invoked by CampaignEvent::Dispatch() to allow the EventCoordinator to act as a node container and have access to all its constituent nodes via the INodeEventContext interface.

Note

The AddNode calls actually come via a delegate function that is in the EventCoordinator, but is invoked from the VisitNodes method up in the SimulationEventContext. The CampaignEvent passes the delegate function it wants used when it calls SimulationEventContext::VisitNodes() . This circuitous journey is needed because EMOD operates on a node-by-node basis and the SimulationEventContext, not the CampaignEvent, is the primary node container.

CreateInstance()

During their instantiation, CampaignEvents create EventCoordinators as the CampaignEvents parse the Event_Coordinator_Config, which specifies the class name and is passed by SimulationEventContext. Nothing then happens until CampaignEvent::Dispatch() is called.

IsFinished()

When an EventCoordinator determines that it is finished distributing its interventions, it sets an internal flag. The SimulationEventContext queries the IsFinished() function on each registered EventCoordinator and disposes of it if true. An EventCoordinator can activate and complete in a single time step, or it could last the entire length of the simulation.

Update()

The SimulationEventContext calls this on all registered EventCoordinators to advance their state at each time step. This method exists for global EventCoordinator communication and logic.

UpdateNodes()

Distributes the actual intervention. For the simplest possible use case, an EventCoordinator will distribute an intervention on its start day and then finish in that same time step. However, an EventCoordinator may implement repeating interventions, phased distributions, or sustained distributions that are contingent on node or individual attributes.

Outgoing: The outgoing function calls consist of the distribution of the intervention either to individuals or nodes. For the interface between the EventCoordinator and the actual Intervention, the EventCoordinator calls InterventionFactory and passes it the remaining unparsed JSON from the campaign file. Namely, this is the Intervention_Config, the actual intervention-level campaign parameters including the intervention class. The InterventionFactory returns the newly created intervention instance for each individual via a one of two types of IDistributableIntervention interfaces.

Interventions

Interventions are the actual objects aimed at reducing the spread of disease, such as a vaccine or drug. THey can be either distributed to individuals or to nodes. For example, a vaccine is an individual-distributed intervention and a larvicide is a node-distributed intervention. Intervention is an abstract type class and specific interventions are classes that implement either IDistributableIntervention, for individual-distributed interventions, or INodeDistributableIntervention, for node-distributed interventions.

The determination of whether an intervention is individual-distributed or node-distributed is contained by logic in InterventionFactory. At the beginning of the EventCoordinator::UpdateNodes()**method, the **InterventionFactory is queried with the unparsed JSON campaign file to see if it returns an INodeDistributableInterface pointer. If it does, the intervention is executed as a node-distributed intervention; if it does not, the individual- distributed intervention execution is used.

Incoming: The interface to the abstract type Intervention class is the Distribute() method. It functions slightly differently for each intervention type.

Outgoing: Intervention is an abstract type that interacts with Nodes or IndividualHumans with an interface specific to that intervention type. The intervention calls QueryInterface on the container to ask for a consumer interface, for example IBednetConsumer. If supported, a Give method specific to that intervention will be called, for example, GiveBednet(this) to give itself to this individual. It is then up to the internal IndividualHuman or Node logic to decide what to do with this intervention.

Individual-distributed interventions

An individual-distributed intervention implements IDistributableIntervention, a container for the actual parameter name-value pairs from the campaign file, that is contained by an IndividualContainer, an IndividualHuman helper class. The EventCoordinator calls IDistributableIntervention::Distribute(), passing the pointer IIndividualHumanDistributionContext, which provides an ISupports interface to the individual by which the intervention can request a consumer interface. This interface can then be used with Give().

In the EventCoordinator::UpdateNodes() method, the EventCoordinator organizes the distribution of Interventions to IndividualHumans mediated by Nodes, which contain the IndividualHuman objects. The EventCoordinator also applies campaign parameters at the event coordinator level (for example, Target_Demographic, Demographic_Coverage, Num_Repetitions, and Days_Between_Reps) which mainly consists of filtering the distribution to individuals based on individual attributes.

Node-distributed interventions

A node-distributed intervention implements INodeDistributableIntervention, a container for the actual parameter name-value pairs from the campaign file, that is contained by a Node. The EventCoordinator calls INodeDistributableIntervention::Distribute(), passing the pointer INodeEventContext, which provides an ISupports interface to the individual by which the intervention can request a consumer interface. This interface can then be used with Give(). Similar to individual-distributed interventions, the EventCoordinator also applies campaign parameters for filtering the distribution.

The architectural diagram below illustrates how campaign file settings are processed by an EMOD simulation.

_images/ArchCampaignFlow.png

EMOD campaign architecture

Reporter component

After running simulations, EMOD creates output reports that contain the model results. Two methods of coordinated reporting are implemented: simulation-wide aggregated reporting and spatial reporting. See Output files (reports) for more information about the different output reports available.

Simulation-wide aggregate

Simulation-wide aggregate reporting is the most commonly used. This reporting method generates the output written to InsetChart.json. Conceptually, for each time step, the value of a named channel is derived from values provided for that channel by each node. The values are accumulated (summed) over all nodes and then transformed (often normalized by an internal parameter or another channel) just prior to writing. This is implemented through the simulation’s insetChartDataAccumulator.

Basic usage of the NodeTimestepDataAccumulator is explained in Report.h. The simulation is responsible for calling Begin/EndTimestep() and collecting and writing out the data at the end of the simulation. The accumulation calls occur in Node::accumulateInsetChartData().

Spatial

The second method is spatial reporting which is facilitated by SpatialReporter. In spatial reporting, each node again produces values for named channels, but no simulation-wide accumulation takes place. Instead, the values of each channel for each node are written to a binary table (ReportNNNN.dat) where NNNN is the time step. The format of this file is simple and can be summarized as the maximally packed layout of this structure:

struct ReportDataFormat
{
    int32_t num_nodes;
    int32_t num_channels;
    float data[num_nodes*num_channels];
}

Num_Channels is the number of user channels implicitly generated by the number of different channel names requested in calls to Node::reportSpatialDataReportChannels() plus two additional channels for longitude and latitude. JSON metadata for the ReportNNNN.dat files is written to Report.header.dat after the first time step. It does not include entries for latitude and longitude.

In general, the value of channel \(c\) for node \(n\), starting at zero, is found at \(data[n\times num\_channels+c]\). The latitude is \(data[n\times num\_channels+0]\) and the longitude is \(data[n\times num\_channels+1]\).

The report data files are written after every time step at the request of the Controller by calling WriteTimestep(). Under MPI, the default implementation reduces all the data to rank 0 and writes the combined data out to file on rank 0.

See Custom reporters for information about how to use a custom reporter.

Debugging and testing

When you build Eradication.exe or Eradication binary for Linux from the EMOD source code, it’s important to debug the code and run regression tests to be sure your changes didn’t inadvertently change EMOD functionality. You can run simulations directly from Visual Studio to step through the code, troubleshoot any build errors you encounter, and run the standard EMOD regression tests or create a new regression test.

Warning

If you modify the source code to add or remove configuration or campaign parameters, you may need to update the code used to produce the schema. You must also verify that your simulations are still scientifically valid.

Set log levels

EMOD simulations output several files, including log files. See Error and logging files for more information on the logging files that are created by a simulation. By default, logging is at the “INFO” level, but you can set the level at which you want logging information generated. If you see redundant log messages, you can also throttle logging to eliminate them.

There are five log levels. The level chosen will log messages for that level and all higher levels (levels of smaller numeric value). You can set default log levels across the entire Eradication.exe or for individual files in the Eradication.exe; individual file settings will override the default. For example, if you want to increase logging for a particular file you are debugging without increasing logging across the entire Eradication.exe, you can set the default log level to “WARNING” and set the log level for the file to “DEBUG”. The standard output will reflect the default log level for all settings except “ERROR” or “WARNING”. For example:

Log-levels:
        Default -> INFO
        Eradication -> INFO

The following log levels are available:

ERROR (1)

This is the highest level. Only errors, including critical errors, are logged to standard output.

WARNING (2)

Warnings and errors are logged to standard output.

INFO (3)

This is the default logging level for the executable and is set implicitly. Informational messages, warnings, and errors are logged to standard output.

DEBUG (4)

Debug information, informational messages, warnings, and errors are logged to standard output. Debug level logging messages do not require a debug build of Eradication.exe. This setting will generate a large number of messages and may impact performance. If you need the debugging messages, we recommend that you limit the number of files with this setting and not set it as the default across the entire Eradication.exe.

VALID (5)

This is the lowest level. Validation information, debug information, informational messages, warnings, and errors are logged to standard output. This log level is for very low-level debugging of specific values, including values in tight loops. Because it could severely impact performance, this level will only output to standard output during a debug build of Eradication.exe.

Set default Eradication.exe level

To set the default log level across the entire Eradication.exe, add the parameter logLevel_default to your configuration file and set it to the log level desired. For example:

{
    "logLevel_default": "WARNING"
}
Set level for individual files

You can set the log level for an individual file, if it supports the ability. This is typically only used for debugging after making source code changes. This setting will override the default set using logLevel_default, whether set to a higher or lower level.

  1. In the C++ files that make up the EMOD source code, open the file for which you want to set the log level.

  2. Search for static const char * _module.

    “Module” refers to the C++ file and is not the same as an EMODule. If this string isn’t present, you cannot set a log level for the file.

  3. Look for logging macros in the file, such as LOG_WARN(x).

    If macros are present, this indicates that the file supports that log level setting. The file may not support all log levels. Logging macros can be found in utils/Log.h. You can also add your own logging messages to the file using the logging macros.

  4. In the configuration file, add the logLevel_<FileName> parameter with the log level desired. For example:

    {
    "logLevel_SimulationVectorExport":"DEBUG"
}
Throttle redundant logging

It’s possible that multiple identical logging messages are generated by a file of Eradication.exe. This is normal behavior, but the verbosity can be unwanted or unnecessary. You can eliminate duplicate messages by turning on “throttling”, which retains only one logging message instead of a series of duplicate messages from each file.

Only one copy of the message will be generated when it is one of a series of duplicates from the same file. The identical messages need not be output one right after one another to be throttled. If an identical message is output from a different file, it will still be generated. Throttling can only be enabled across the entire Eradication.exe, not per file. It is off by default.

To enable throttling, add the following parameter and value to your configuration file:

{
    "Enable_Log_Throttling": 1
}

For example, the following log messages are seen with throttling turned off:

00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] another message from B
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] different message from B
00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] yet another message from B.
00:00:00 [0] [D] [FileA] identical message: I'm in FileA

With throttling on, the repeated messages from file A are removed, even though they are intermixed with other log messages from file B:

00:00:00 [0] [D] [FileA] identical message: I'm in FileA
00:00:00 [0] [D] [FileB] another message from B
00:00:00 [0] [D] [FileB] different message from B
00:00:00 [0] [D] [FileB] yet another message from B.

Run debug simulations in Visual Studio

If you have modified the EMOD source code, you can run simulations directly from Visual Studio as part of debugging your changes by using the built-in debugger. For example, you may want to run one or more of the simulations in the Regression directory to verify that the results match those obtained prior to your changes.

  1. Open the EradicationKernel solution in Visual Studio.

  2. On the Solution Explorer pane, right-click the Eradication project and select Properties.

  3. On the Property Pages window, in the Configuration Properties pane, click Debugging.

  4. Set the Command Arguments and Working Directory to the appropriate values and click OK. See Run a simulation using the command line for more information.

  5. On the Debug menu, do one of the following:

    • Click Start Without Debugging to run the simulation in Release mode, where the simulation runs with essentially the same behavior and performance as running it at the command line.

    • Click Start Debugging to run the simulation in Debug mode, where you have the ability to add break points and step through the code, inspecting the values of different variables throughout the simulation.

Troubleshooting EMOD builds

If you encounter any of the following warnings or errors when attempting to build the EMOD executable (Eradication.exe) or Eradication binary for Linux, see the information below to resolve the issue.

If you need assistance, you can contact support for help with solving issues. You can contact Institute for Disease Modeling (IDM) support at support@idmod.org. When submitting the issue, please include any error information.

Unknown compiler version

If you encounter the warning “Unknown compiler version - please run the configure tests and report the results” when attempting to build the Eradication.exe or Eradication binary for Linux, this indicates you are using a version of Boost that is no longer supported. Install Boost 1.77.0.

Inconsistent DLL linkage

If you see the following warning on some files, “c:python27includepymath.h(22): warning C4273: ‘round’: inconsistent dll linkage”, this indicates that you are using a version of Python that is no longer supported. Install Python 3.9 64-bit.

Error 255

Check to see if you have any white spaces in the path to your local EMOD source code. If you do, remove the white spaces in all of the directory names in the path.

Error LNK4272

If you see the error “LNK4272 library machine type ‘X86’ conflicts with target machine type ‘x64’”, this indicates that you need to uninstall 32-bit Python and reinstall 64-bit Python. Install Python 3.9 64-bit.

Regression testing

After building the EMOD executable (Eradication.exe), it’s important to verify that Eradication.exe is performing properly. Regression testing is a method by which the built code is tested to see if it has “regressed” or moved backwards in any way, such as previously reported (and fixed) issues reappearing.

Within the EMOD Regression directory there are many subdirectories that correspond to different disease scenarios in a variety of locations. Each of these contains the configuration and campaign files needed to run the simulation and the reference output, which represents the expected results. These reference outputs have been calculated by the scientific researchers modeling each scenario. Configurations and campaigns that use base and overlay files will be flattened as part of the regression tests.

EMOD regression testing consists of running one or more of these simulations and comparing the output to the reference output. If the two outputs are comparable, the test passes; if they differ, the test fails. Because EMOD is stochastic, a passing test will fall within some acceptable range of the reference output, rather than be an identical match. If a regression test fails, EMOD will produce a matplotlib chart of the first 16 channels in the InsetChart.json output report. You can then review the charts to identify the problem. Base and overlay configuration files will be flattened

If you want to quickly compare a simulation output to the reference output, you can also run any of the regression scenarios as a typical simulation, as described in Running a simulation. However, this will not include the comparison and pass/fail evaluation that regression_test.py conducts. In addition, if you choose to do this, be sure to specify a different output directory, such as “testing”, so as not to overwrite the reference output.

Run regression tests

The Python script regression_test.py runs a suite of regression simulations and compares the output to the reference output for each simulation. It is set up to run the simulations on an HPC cluster; however, you can run modify the script to run tests locally. However, the script was written with remote execution in mind and running it locally can be time-consuming. Running the entire regression suite locally will take several hours on average.

The regression scenarios, script, configuration file, and other relevant files are all in the Regression directory. Be aware that many of these tests, due to abnormally high or low values, will produce output that should not be considered scientifically accurate.

  1. Modify the configuration file, regression_test.cfg, for your environment, setting the values for the location of the working directory, input files, binary file, and cluster settings.

    • For local Windows simulations, set the values under [WINDOWS].

    • For local CentOS simulations, set the values under [POSIX]. Note that CentOS simulations are run locally by default and cannot be commissioned to an HPC cluster.

    • For simulations on IDM HPC clusters, no changes are necessary if your username and password are cached locally.

    • For simulations on your own HPC cluster, create [HPC-<cluster>] and [ENVIRONMENT-<cluster>] sections for your cluster that contain the same variables as shown for IDM HPC clusters.

  2. Select the suite of regression tests you want to run. This is indicated by a JSON file in the following format:

    {
    "tests": [{
        "path": "Relative path to test directory."
    }, {
        "path": "Relative path to test directory."
    }]
}

    You can use one of the JSON files in the Regression directory or create your own. The sanity.json file is recommended for quickly testing a wide range of EMOD functionality.

  3. From the Regression directory, open a Command Prompt window and run the regression test script, regression_test.py. It requires the name of the regression suite (without the .json extension) and the relative path to Eradication.exe. For example:

    regression_test.py sanity ..\Eradication\x64\Release\Eradication.exe

    In addition, you may need to include the following optional arguments depending on your testing environment or how Eradication.exe was built.

    Argument

    Default

    Description

    --perf

    False

    Measure Eradication.exe performance.

    --hidegraphs

    False

    Suppress pop-up graphs in case of validation failures.

    --debug

    False

    Use the debug path for EMODules.

    --label

    Add a custom suffix for HPC job name.

    --config

    regression_test.cfg

    The regression test configuration file.

    --disable-schema-test

    True

    Include to suppress schema testing, which is on by default.

    --use-dlls

    False

    Use EMODules when running tests.

    --all-outputs

    False

    Use all output JSON files for validation, not just InsetChart.json.

    --dll-path

    The path to the root directory of the EMODules to use.

    --skip-emodule-check

    False

    Skip checking if EMODules on the cluster are up-to-date, which can be slow.

    --scons

    False

    Indicate that this is a SCons build so custom DLLs are found in the build/64/Release directory.

    --local

    False

    Run all simulations locally.

  4. Review the output and examine any failures.

    EMOD will output the standard error and logging files, StdErr.txt and StdOut.txt, produced from any simulation (see Error and logging files). In addition, regression_test.py will output time.txt under the regression test working directory and report_xxxx.xml under Regression/reports. The time report contains the EMOD version and total run time of the simulation. The regression report is in JUnit standard form and captures run information, including pass/fail/complete and time to complete.

    If a simulation completes saying the run passed but the channel order was different than the reference output, this is considered a pass. However, if any output completes but does not match the reference output, this is considered a failure and a matplotlib chart of the output will appear in a pop-up window. The chart will appear immediately after the simulation, before the entire suite of regression tests completes. You can manipulate the output of the charts, such as adjusting the scale of the plots, zooming or panning, and so forth, through the icons at the bottom of the chart window.

    _images/matplotlibPopupChart.png

If any of the regression tests fail and you have not made any changes to the EMOD source code, email support@idmod.org.

Create a new regression test

You can create a new regression based off one of the ones included with the EMOD source code using the steps below.

  1. Under the Regression directory, create a new subdirectory.

  2. Copy the contents of the regression test that you want to base the new test on into the subdirectory.

  3. Modify the configuration, campaign, and demographic files as desired.

  4. Create the reference output by doing one of the following:

    • Modify the InsetChart.json file to match the output you expect.

    • Run simulations until you have an acceptable InsetChart.json that you wish to use as the reference.

Scientific feature testing

Scientific feature testing (SFT) verifies that EMOD features are functioning as expected. That is, they are requirements-based tests of model features that are quantitatively verified. They are implemented as a Python post-processing script named dtk_post_process.py.

All of the files can be found in the Regression directory of the EMOD GitHub repository.

Run locally

If you are running locally without access to an HPC, do one the following depending on your operating system:

Run on Windows using regression_test.py

  1. In the Regression directory, edit the regression_test.cfg file to list the directories where you want the simulations to be run and output saved.

  2. Make a file listing all of the SFTs you want to run, using on of the files in Regression<sim>_science.json as an example.

  3. From the Regression directory in a command prompt window, run the following, adding --scons if you built the Eradication.exe using SCONS:

    python regression_test.py my_sfts.json --local

    Note

    Enter python regression_test.py --help for a list of all arguments you can use with the testing script.

Run on Windows using run_test.cmd

  1. Generate a single config.json file from a base file and the parameter_overrides.json that contains (see Configuration overlay files for instructions).

  2. Navigate to the directory that contains your config.json file and other test files.

    Note

    Verify in the config.json file that the paths to the demographics and other additional input files are correct.

  3. In a command prompt window, enter the following, substituting your path to the testing script as necessary:

    ../../run_test.cmd
Run on CentOS using run_test.sh

  1. Generate a single config.json file from a base file and the parameter_overrides.json that contains (see Configuration overlay files for instructions).

  2. Navigate to the directory that contains your config.json file and other test files.

    Note

    Verify in the config.json file that the paths to the demographics and other additional input files are correct.

  3. In a command prompt window, enter the following, substituting your path to the testing script as necessary:

    ../../run_test.sh