Configure heterogeneous populations¶
Demographics files are used to add heterogeneity to a population. You can define the initial distribution to use for age, prevalence, risk and more. You can also define values for accessibility, age, geography, risk, and other properties and assign individuals to groups based on those property values. This topic describes how to configure the population distribution and define heterogeneous groups.
After you set up the groups, you may want to add more parameters to the demographics file to configure how individuals transition into and out of groups, how transmission occurs between different groups, or how to target interventions to specific groups. For more information about the parameters and structure of demographics files, see Demographics file structure and parameters.
For example, you might want to divide a population up into different groups 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 areas that are easy to access and lower for individuals in areas that are difficult to access. For more information on targeting interventions to particular groups, see Target interventions to nodes or groups. For information on how tp configure disease transmission among groups created with any of the properties, see Configure heterogeneous disease transmission.
Nodes are subregions within the geographic area being modeled. Values in the Defaults section of the demographics file will be applied to all nodes, while values in the Nodes section will be applied only to the specified node. Node-level settings take precedence.
Define the initial population distribution¶
You can configure attribute distributions in the population using the IndividualAttributes parameter in the demographics file. The initial value for an individual is a randomly selected value from the 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.
In the demographics file, add the IndividualAttributes parameter and assign it an empty JSON object. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
Within this object, add the parameters for different attributes (age, prevalence, etc.) and assign values for available distributions (constant, Gaussian, etc.) See Demographics file structure and parameters for more information about the available parameters.
The example below shows how to set up the age distribution for all nodes in a simulation.
{
"Defaults": {
"IndividualAttributes": {
"AgeDistributionFlag": 3,
"AgeDistribution1": 0.8,
"AgeDistribution2": 0.1
}
}
}
Create groups for properties other than age¶
Assigning individuals to different groups based on properties, such as accessibility or risk, uses the IndividualProperties parameter in the demographics file. See Demographics file structure and parameters for a list of supported properties. The values you assign to properties are use-defined and can be applied to individuals in all nodes or only in particular nodes in a simulation.
In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
In the array, add an empty JSON object. Within it, do the following:
Add the Property parameter and set it to one of the supported values.
Add the Values parameter and set it to an array of possible values that can be assigned to individuals. You can define any value here.
Add the Initial_Distribution parameter and set it to an array of numbers that add up to 1. This configures the initial distribution of individuals assigned to each of the groups.
To define how individuals transition into and a out of each group, add the Transitions parameter and set it to it an empty array. Within it, do the following:
Add an empty JSON object and set parameters that define the group that individuals transition from, the group they transition to, the event that triggers the transition, the probability of transition, and more. See doc:parameter-demographics for a list of supported Transitions parameters and values.
If you want to add another property and associated groups, 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 groups for age ranges¶
Creating groups based on age ranges works a little differently than creating groups based on 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. Because of this, the parameters and structures in IndividualProperties are slightly different.
In the demographics file, add the IndividualProperties parameter and set it to an empty array. If you want the groups to apply to all nodes, add it in the Defaults section; if you want the groups to be applied to specific nodes, add it to the Nodes section.
In the array, add an empty JSON object. Within it, do the following:
Add the Property parameter and set it to “Age_Bin”.
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.
To define how individuals transition into and a out of each group, add the Transitions parameter and set it to it an empty array. Aging during the simulation will be handled by EMOD.
The example below shows how to set up several groups based on disease risk and physical place, and how to move individuals among these groups. 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],
"Transitions": [{
"From": "High",
"To": "Medium",
"Type": "At_Age",
"Coverage": 1,
"Probability_Per_Timestep": 0.3,
"Timestep_Restriction": 20,
"Age_In_Years": 5,
"Timesteps_Until_Reversion": 0
}, {
"From": "Medium",
"To": "Low",
"Type": "At_Age",
"Coverage": 1,
"Probability_Per_Timestep": 0.3,
"Timestep_Restriction": 20,
"Age_In_Years": 12,
"Timesteps_Until_Reversion": 0
}]
}, {
"Property": "Place",
"Values": ["Community", "School", "Work", "Vacation"],
"Initial_Distribution": [0.3, 0.2, 0.4, 0.1],
"Transitions": [{
"From": "School",
"To": "Vacation",
"Type": "At_Timestep",
"Coverage": 1,
"Timestep_Restriction": {
"Start": 20
},
"Age_In_Years_Restriction": {},
"Probability_Per_Timestep": 1,
"Timesteps_Until_Reversion": 20
}]
}, {
"Property": "Age_Bin",
"Age_Bin_Edges_In_Years": [0, 5, 13, -1],
"Transitions": []
}]
}
}