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": {},
     },
     "Nodes": [{
          "NodeID": 1,
          "NodeAttributes": {},
          "IndividualAttributes": {},
          "IndividualProperties": {},
     }, {
          "NodeID": 2,
          "NodeAttributes": {},
          "IndividualAttributes": {},
          "IndividualProperties": {},
     }]
}

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.

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

[]

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.

{
  "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
        ]
      }
    ]
  }
}

Transitions

array

NA

NA

NA

An array that contains multiple JSON objects that each define how an individual transitions from one property value to another. See the transitions array table for information about the parameters to include in the Transitions 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. Cannot be used with NodeProperties.

{
  "Defaults": {
    "IndividualProperties": [
      {
        "Transitions": [
          {
            "From": "High",
            "To": "Medium",
            "Type": "At_Age",
            "Coverage": 1,
            "Probability_Per_Timestep": 0.3,
            "Age_In_Years": 5,
            "Timesteps_Until_Reversion": 0
          },
          {
            "From": "Medium",
            "To": "Low",
            "Type": "At_Age",
            "Coverage": 1,
            "Probability_Per_Timestep": 0.3,
            "Age_In_Years": 12,
            "Timesteps_Until_Reversion": 0
          }
        ]
      }
    ]
  }
}

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
        }
    }
}

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

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
                }
            }
        }
    }
}