Demographics file structure and parameters¶
The parameters described in this reference section can be added to the JavaScript Object Notation (JSON) 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. This is in contrast to the configuration parameters related to demographics that are simulation-wide and generally control whether certain events, such as births or deaths, are enabled in a simulation.
At least one demographics file is required for every simulation unless you set the parameter Enable_Demographics_Builtin to 0 (zero) in the configuration file. This is generally only used for testing and validating code pathways by using a standard testing sandbox instead of actual demographics information. If Migration_Model is set to “FIXED_RATE_MIGRATION”, built-in demographics will use a form of local migration where individuals migrate only to adjacent nodes.
Demographics files are usually the only input data file you will modify. Demographics files are named using the name of the region, appended with “_demographics.json”.
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.
Contents
Demographic file structure¶
Demographics files are organized into three sections:
- Metadata
Information such as data source, created date or region name. Metadata is used to provide provenance information.
- Defaults
Default parameter values applied to all nodes.
- Nodes
Parameter values specific to individual geographic nodes, which override the default values. There is one entry for each node in the simulation.
The following example shows the skeletal format of a demographics file.
{
"Metadata": {
"DateCreated": "dateTime",
"Tool": "scriptUsedToGenerate",
"Author": "author",
"IdReference": "ID reference",
"NodeCount": 2
},
"Defaults": {
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
},
"Nodes": [{
"NodeID": 1,
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
}, {
"NodeID": 2,
"NodeAttributes": {},
"IndividualAttributes": {},
"IndividualProperties": {}
}]
}
Metadata¶
Most of the items in the Metadata section informational only and are not used by EMOD. This includes information such as author, date created, and tool used to create the file. However, the following two values are used by EMOD:
- NodeCount
The number of nodes to expect in the demographics file.
- IdReference
The unique string that indicates the method used for generating the NodeID, the identifier used for each node in the simulation.
See Input data file structure for more information about IdReference and NodeID generation.
Defaults¶
Parameter values in the Defaults section is applied to all nodes. However, any node-level information provided in the Nodes section will take precedence for that node. The Defaults section is optional and can be completely omitted, as is often the case of single- node simulations. The Defaults section can contain any of the parameters listed below.
Nodes¶
Parameter values in the Nodes section is applied to specific nodes. The intent of the Nodes section is to have only the information that is unique to each node, such as identifier and location (longitude and latitude). The section contains an array with each element in the array representing a node that is identified by its NodeID. The NodeID is a unique integer value. If a parameter appears in both the Defaults and Nodes sections, the value in the Nodes section will take precedence.
Parameters¶
The demographic parameters are divided into the following broad categories. The parameters will be contained in a nested JSON object of the same name.
Warning
Parameters are case-sensitive. For Boolean parameters, set to 1 for true or 0 for false.
NodeAttributes¶
NodeAttributes are a JSON object 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.
IndividualAttributes¶
IndividualAttributes are a JSON object 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.
There are two types of distributions: simple and complex. Simple distributions are defined by three parameters where one is the distribution type and the other two are used to further define the distribution. You can use complex distributions to define a distribution that does not fit some standard. For example, a complex distribution is useful when trying to represent real-world data.
The table below shows the simple distributions and their associated parameters.
Distribution |
Demographic parameters |
Related configuration parameters |
|---|---|---|
Age |
|
Age_Initialization_Distribution_Type must be set to “DISTRIBUTION_SIMPLE”. |
Prevalence |
|
Enable_Demographics_Other must be set to 1. |
Immunity |
|
|
Risk |
|
Enable_Demographics_Other must be set to 1. |
Migration heterogeneity |
|
Enable_Migration_Heterogeneity must be set to 1. |
The table below shows the available probability distribution types to use with simple distributions and how to set the other two demographic parameters to initialize the distribution.
Distribution type |
Flag value |
Distribution1 value |
Distribution2 value |
|---|---|---|---|
Constant |
0 |
Value |
N/A (set to 0) |
Uniform |
1 |
Minimum |
Maximum |
Gaussian |
2 |
Mean |
Standard deviation |
Exponential |
3 |
Mean |
N/A (set to 0) |
Poisson |
4 |
Mean |
N/A (set to 0) |
Log normal |
5 |
Mean |
Log (standard deviation) |
Bimodal |
6 |
Proportion of time to return the value specified by Distribution2. Value must be between 0 and 1. |
A positive value to be returned. If the value is not positive, a value of 1 is returned. |
Weibull |
7 |
Scale parameter |
Shape parameter |
EMOD also supports the following complex distributions:
AgeDistribution
FertilityDistribution
MortalityDistribution
MortalityDistributionMale
MortalityDistributionFemale
HIVCoinfectionDistribution
HIVMortalityDistribution
MSP_mean_antibody_distribution
nonspec_mean_antibody_distribution
PfEMP1_mean_antibody_distribution
MSP_variance_antibody_distribution
nonspec_variance_antibody_distribution Malaria
PfEMP1_variance_antibody_distribution
IndividualProperties¶
IndividualProperties are a JSON array that contains parameters that add properties to individuals in a simulation as a means of setting up groups. For example, you can define values for accessibility, age, geography, risk, and other properties and assign individuals to different groups based on those property values.
Parameter |
Data type |
Description |
Example |
|---|---|---|---|
Property |
string |
The property type for which you will assign values to create groups. Accepted values are:
|
{
"IndividualProperties": [{
"Property": "Risk"
}]
}
|
Values |
array |
An array of the user-defined values that can be assigned to individuals for this property. You can have up to 125 values for the Geographic property type and up to 5 values for all other types. For “Age_Bin” property types, omit and use Age_Bin_In_Years instead. |
{
"IndividualProperties": [{
"Values": ["Low", "Medium", "High"]
}]
}
|
Initial_Distribution |
array |
An array of numbers that define the proportion of individuals to assign to each group at the beginning of the simulation. Their total 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. |
{
"IndividualProperties": [{
"Initial_Distribution": [0.2, 0.4, 0.4]
}]
}
|
Age_Bin_In_Years |
array |
An array of integers that represents the ages, in years, at which to demarcate the age groups. 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. |
The following example creates three age groups: 0 to 5, older than 5 to 13, and older than 13 to the maximum age. {
"IndividualProperties": [{
"Age_Bin_In_Years": [0, 5, 13, -1]
}]
}
|
Transitions |
array |
An array contains multiple JSON objects that each define how an individual transitions from one property group to another. See the following table for information about the parameters to include in the object. For “Age_Bin” property types, set to an empty array, as individuals will transition to the next age bin based on the passing of time. |
{
"IndividualProperties": [{
"Transitions": []
}]
}
|
TransmissionMatrix |
array |
An object that contains Route and Matrix parameters that define how to scale the base infectivity from individuals in one group to individuals in another. See Configure heterogeneous disease transmission for more information. |
{
"IndividualProperties": [{
"TransmissionMatrix": {
"Route": "Contact",
"Matrix": [
[10, 0.1],
[0.1, 1]
]
}
}]
}
|
The following table contains the parameters that are available to use in the Transitions array.
Parameter |
Data type |
Description |
Example |
|---|---|---|---|
From |
string |
Which group an individual will transition from. |
{
"Transitions": [{
"From": "Low"
}]
}
|
To |
string |
Which group an individual will transition to. |
{
"Transitions": [{
"To": "High"
}]
}
|
Type |
string |
The type of condition that starts transitioning individuals. Set to “At_Age” or “At_Timestep”. The other parameters you must set depend on the condition type set here. |
{
"Transitions": [{
"Type": "At_Age"
}]
}
|
Age_In_Years_Restriction |
nested JSON object |
The age when an individual is eligible to transition. Min is optional and Max is required. Do not use this with “At_Age” types because it will conflict with other age parameters in Age_In_Years. This is required for “At_Timestep” types, though it can be empty for no age restriction. |
{
"Transitions": [{
"Type": "At_Timestep",
"Age_In_Years_Restriction": {
"Min": 5,
"Max": 40
}
}]
}
|
Timestep_Restriction |
nested JSON object |
The time step when transitioning starts and stops. Required for both “At_Age” and “At_Timestep” types. Start is required and End is optional. |
{
"Transitions": [{
"Timestep_Restriction": {
"Start": 20
}
}]
}
|
Coverage |
float |
A value between 0 and 1 that indicates the proportion of the population that EMOD will attempt to transition. The calculation used with Probability_Per_Timeset only uses the proportion of the population specified in Cover to calculate the probability of an individual transitioning at a given time step. Coverage has no effect when the value is set to 1. Required for both “At_Age” and “At_Timestep” types. |
{
"Transitions": [{
"Coverage": 0.5
}]
}
|
Probability_Per_Timestep |
float |
A value between 0 and 1 that is used to calculate the probability of an individual transitioning at the current time step given the number of individuals remaining in the group. Required for both “At_Age” and “At_Timestep” types. |
{
"Transitions": [{
"Probability_Per_Timestep": 0.25
}]
}
|
Age_In_Years |
integer |
The age at which individuals are eligible to transition. Do not use for “At_Timestep” types. Required for “At_Age” types. |
{
"Transitions": [{
"Type": "At_Age",
"Age_In_Years": 10
}]
}
|
Timesteps_Until_Reversion |
integer |
The number of time steps after the start of transitioning when individuals revert back to their original group. The start of transitioning is specified by the Start parameter in Timestep_Restriction. |
{
"Transitions": [{
"Timestep_Restriction": {
"Start": 20
},
"Timesteps_Until_Reversion": 100
}]
}
|
Example¶
The example below shows a complete multi-node demographics file that uses a gridded IdReference type.
{
"Metadata": {
"DateCreated": "03/03/2016",
"Tool": "DemographicsWorker",
"Author": "Institute for Disease Modeling",
"NodeType": "Grid",
"ProjectName": "IDM-Madagascar",
"RegionName": "Madagascar",
"IdReference": "Gridded world grump2.5arcmin",
"NodeCount": 15,
"DataProvenance": "Generated by internally-developed demographic tools",
"Resolution": 150,
"UpperLatitude": -10.6666666666667,
"LeftLongitude": 41.6666666666667,
"BottomLatitude": -27.3333333333333,
"RightLongitude": 51.3333333333333
},
"Defaults": {
"NodeAttributes": {
"Altitude": 0,
"Airport": 0,
"Region": 1,
"Seaport": 0,
"BirthRate": 0.000102,
"AbovePoverty": 0
},
"IndividualAttributes": {
"AgeDistributionFlag": 3,
"AgeDistribution1": 0.00015,
"AgeDistribution2": 0,
"PrevalenceDistributionFlag": 1,
"PrevalenceDistribution1": 0.1,
"PrevalenceDistribution2": 0.2,
"ImmunityDistributionFlag": 0,
"ImmunityDistribution1": 1,
"ImmunityDistribution2": 0,
"RiskDistributionFlag": 0,
"RiskDistribution1": 1,
"RiskDistribution2": 0,
"MigrationHeterogeneityDistributionFlag": 0,
"MigrationHeterogeneityDistribution1": 1,
"MigrationHeterogeneityDistribution2": 0,
"MortalityDistribution": {
"NumDistributionAxes": 2,
"AxisNames": ["gender", "age"],
"AxisUnits": ["male=0,female=1", "years"],
"AxisScaleFactors": [1, 365],
"NumPopulationGroups": [2, 3],
"PopulationGroups": [
[0, 1],
[0, 100, 2000]
],
"ResultUnits": "annual deaths per 1000 individuals",
"ResultScaleFactor": 0.00000273972602739726027397260273973,
"ResultValues": [
[0, 20.0000035, 400.00007],
[0, 20.0000035, 400.00007]
]
}
}
},
"Nodes": [{
"NodeID": 358876977,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.1875,
"Altitude": 34,
"Area": 25,
"InitialPopulation": 2088,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358876978,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.1875,
"Altitude": 19,
"Area": 25,
"InitialPopulation": 1682,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942512,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.2291679382324,
"Altitude": 127,
"Area": 25,
"InitialPopulation": 5160,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942513,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.2291679382324,
"Altitude": 128,
"Area": 25,
"InitialPopulation": 2860,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 358942514,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.2291679382324,
"Altitude": 26,
"Area": 25,
"InitialPopulation": 790,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008047,
"NodeAttributes": {
"Latitude": -13.3958330154419,
"Longitude": 48.2708320617676,
"Altitude": 48,
"Area": 25,
"InitialPopulation": 6436,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008048,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.2708320617676,
"Altitude": 111,
"Area": 25,
"InitialPopulation": 4983,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008049,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.2708320617676,
"Altitude": 124,
"Area": 25,
"InitialPopulation": 1245,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008050,
"NodeAttributes": {
"Latitude": -13.2708330154419,
"Longitude": 48.2708320617676,
"Altitude": 57,
"Area": 25,
"InitialPopulation": 1387,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359008051,
"NodeAttributes": {
"Latitude": -13.2291669845581,
"Longitude": 48.2708320617676,
"Altitude": 66,
"Area": 25,
"InitialPopulation": 1516,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073583,
"NodeAttributes": {
"Latitude": -13.3958330154419,
"Longitude": 48.3125,
"Altitude": 132,
"Area": 25,
"InitialPopulation": 5957,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073584,
"NodeAttributes": {
"Latitude": -13.3541669845581,
"Longitude": 48.3125,
"Altitude": 44,
"Area": 25,
"InitialPopulation": 643,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073585,
"NodeAttributes": {
"Latitude": -13.3125,
"Longitude": 48.3125,
"Altitude": 55,
"Area": 25,
"InitialPopulation": 1171,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359073587,
"NodeAttributes": {
"Latitude": -13.2291669845581,
"Longitude": 48.3125,
"Altitude": 36,
"Area": 25,
"InitialPopulation": 378,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}, {
"NodeID": 359139117,
"NodeAttributes": {
"Latitude": -13.4791669845581,
"Longitude": 48.3541679382324,
"Altitude": 282,
"Area": 25,
"InitialPopulation": 674,
"BirthRate": 0.000113117808219178,
"AbovePoverty": 0,
"Urban": 0
}
}]
}