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 parameter-configuration-population 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.

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 software-demographics.

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.

link

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 generic 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.

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	Example	Description	Type	Min	Max	Default
Author	link	The person who created the demographics file. Files generated by COMPS will include this value, but it is not used by EMOD simulations.	string	nan	nan	nan
DateCreated	link	The date the demographics file was created. Files generated by COMPS will include this value, but it is not used by EMOD simulations.	string	nan	nan	nan
IdReference	link	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.	string	nan	nan	nan
Metadata	link	The structure that contains the metadata for the demographics file.	JSON object	nan	nan	nan
NodeCount	link	The number of nodes to expect in the input files. This parameter is required.	integer	1	Depends on available memory	nan
Resolution	link	The spatial resolution of the demographics file. Files generated by COMPS will include this value, but it is not used by EMOD simulations.	integer	nan	nan	nan
Tool	link	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.	string	nan	nan	nan

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. model-properties provides more guidance.

Parameter	Example	Description	Type	Min	Max	Default
Age_Bin_Edges_In_Years	link	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.	array	nan	nan	nan
IndividualProperties	link	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.	array of objects	nan	nan	nan
Initial_Distribution	link link	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.	array of floats	0	1	1
NodeProperties	link	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.	array of objects	nan	nan	nan
Property	link link	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.	enum	nan	nan	nan
TransmissionMatrix	link	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.	JSON object	nan	nan	nan
Values	link link	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.	array of strings	nan	nan	nan

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	Example	Description	Type	Min	Max	Default
Airport	link	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.	boolean	0	1	0
Altitude	link	The altitude, in meters, for the node. Required, but only used when Climate_Model is set to CLIMATE_KOPPEN.	float	-3.40282e+038	3.40282e+38	0
BirthRate	link	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).	double	0	1	8.715e-05
InfectivityReservoirEndTime	link	The ending of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).	float	InfectivityReservoirStartTime	3.40282e+38	3.40282e+38
InfectivityReservoirSize	link	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).	float	0	3.40282e+38	0
InfectivityReservoirStartTime	link	The beginning of the exogeneous reservoir of infectivity. This parameter is conditional upon the configuration parameter, Enable_Infectivity_Reservoir, being enabled (set to 1).	float	0	3.40282e+38	0
InitialPopulation	link	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).	integer	0	2.14748e+09	1000
Latitude	link	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.	float	3.40282e+038	-3.40282e+38	-1
Longitude	link	Longitude of the node in decimal degrees. This can be used for several things, including defining the size of grid cells.	float	-3.40282e+38	3.40282e+38	-1
NodeAttributes	link	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.	JSON object	nan	nan	nan
Region	link	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.	boolean	0	1	0
Seaport	link	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.	boolean	0	1	0

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	Example	Description	Type	Min	Max	Default
IndividualAttributes	link	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 or .	JSON object	nan	nan	nan
PercentageChildren	link	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.	float	0	1	nan

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	Example	Description	Type	Min	Max	Default
AgeDistribution	link	The structure defining a complex age distribution. Age_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX.	JSON object	nan	nan	nan
AxisNames	link	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.	array of strings	nan	nan	nan
AxisScaleFactors	link	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.	array of floats	3.40282e+38	-3.4e+38	1
AxisUnits	link	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.	array of strings	nan	nan	nan
DistributionValues	link	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).	array of floats	0	1	1
FertilityDistribution	link	The distribution of the fertility rate in the population. Enable_Birth in the configuration file must be set to 1 (see Population dynamics parameters).	JSON object	nan	nan	nan
ImmunityDistribution	link	The structure defining a complex immunity distribution. Immunity_Initialization_Distribution_Type in the configuration file must be set to DISTRIBUTION_COMPLEX (see Immunity parameters).	JSON object	nan	nan	nan
MortalityDistribution	link	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.	JSON object	nan	nan	nan
NumDistributionAxes	link	The number of axes to use for a complex distribution. EMOD does not use this value; it is only informational.	integer	1	nan	nan
NumPopulationGroups	link	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.	array of integers	nan	nan	nan
PopulationGroups	link	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.	matrix of integers	nan	nan	nan
ResultScaleFactor	link	The scale factor used to convert ResultUnits to number of births, deaths, or another variable per individual per day.	float	-3.4e+38	3.40282e+38	1
ResultUnits	link	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.	string	nan	nan	nan
ResultValues	link link	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.	array of floats	nan	nan	nan
SusceptibilityDistribution	link	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).	JSON object	nan	nan	nan