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.

For vector and malaria simulations, the same concepts apply to sampling the vector population.

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
}

Mosquito_Weight

integer

1

10000

1

The value indicating how many mosquitoes are represented by a sample mosquito in the simulation. Vector_Sampling_Type must be set to SAMPLE_IND_VECTORS.

 
{
    "Mosquito_Weight": 10
}

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
}

Vector_Sampling_Type

enum

NA

NA

TRACK_ALL_VECTORS

The type of vector sampling used. Possible values are:

TRACK_ALL_VECTORS

Each vector in a node is part of the simulation as a separate object.

SAMPLE_IND_VECTORS

Each vector object in the simulation represents multiple vectors in the node population. Mosquito_Weight sets the number of mosquitos represented by each object.

VECTOR_COMPARTMENTS_NUMBER

Does not track every vector individually, but provides a compartment for every possible entry in state space and tracks the number of vectors in each compartment. This successfully accounts for each vector, but does not distinguish between vectors that have identical states, just counts how many identical vectors of each state are present at a location.

VECTOR_COMPARTMENTS_PERCENT

Similar to VECTOR_COMPARTMENTS_NUMBER, but it only tracks the percentage of the population in each state. Less useful, but included for comparison to other models.

 
{
    "Vector_Sampling_Type": "TRACK_ALL_VECTORS"
}