Skip to content

ReportRelationshipMigrationTracking

The relationship migration tracking report (ReportRelationshipMigrationTracking.csv) provides information about the relationships a person has when they are migrating. It will give information when they are leaving and entering a node. When leaving a node, the information will be about the status of the relationships just before they leave. When entering the new node, the information will be about the relationships that have been updated. For example, a person could leave with a relationship paused, find their partner in the new node, and get their relationship back to normal. This helps to know about how the status of the relationships have changed—migrated, paused, or terminated.

The person initiating a migration event will first have their relationships listed in the state before migrating starts. If a partner is asked to migrate with them, then that partner's relationships will also be listed. When the people are immigrating into the new node, the list of relationships that are continuing in the new node will be listed. Any migrated partner should only have the relationship with the partner initiating migration. Their other relationships will have been terminated.

Configuration

To generate this report, the following parameters must be configured in the custom_reports.json file:

Parameter Data type Min Max Default Description
Filename_Suffix string NA NA "" Augments the filename of the report. If multiple reports are being generated, this allows you to distinguish among the multiple reports.
Start_Year float 1900 2200 1900 Simulation time in years to start collecting data, including fractions of years. For example, 2025.0 means January 1st, 2025.
End_Year float 1900 2200 2200 Simulation time in years to stop collecting data, including fractions of years. For example, 2025.0 means January 1st, 2025.
Node_IDs_Of_Interest array 0 2.14748e+09 [] Data will be collected for the nodes in this list. Leave the array empty (default value) to include all nodes.
Min_Age_Years float 0 9.3228e+35 0 Minimum age in years of people to collect data on.
Max_Age_Years float 0 9.3228e+35 9.3228e+35 Maximum age in years of people to collect data on.
Must_Have_IP_Key_Value string NA NA "" A Key:Value pair that the individual must have in order to be included. Leave the string empty (default value) to not look at individual properties. For more information, see Individual and node properties.
Must_Have_Intervention string NA NA "" The name of an intervention that the person must have in order to be included. Leave the string empty (default value) to not look at the interventions. For more information, see Individual-level interventions. 
{
    "Reports": [
        {
            "Filename_Suffix": "example",
            "Start_Year": 1900,
            "End_Year": 2200,
            "Node_IDs_Of_Interest":[ 1, 2, 3 ],
            "Min_Age_Years": 20,
            "Max_Age_Years": 90,
            "Must_Have_IP_Key_Value": "",
            "Must_Have_Intervention": "",
            "class": "ReportRelationshipMigrationTracking"
        }
    ],
    "Use_Defaults": 1
}

Output file data

The output report will contain the following information.

Data columns

Parameter Data type Description
Time float The simulation time of the migration event—emigrating or immigrating.
Year float The simulation time of the migration event in years.
IndividualID integer The unique ID of the migrating individual.
AgeYears float The age in years of the migrating individual.
Gender string The gender of the individual. Possible values are "M" or "F."
From_NodeID string The external ID of the node the individual is moving from.
To_NodeID string The external ID of the node the individual is moving to, as defined in the demographics. This can be zero when the person has immigrated into the destination node.
MigrationType enum The type of migration that is occurring at the time of the triggering event (see the Event column). If the triggering event is SimulationEnd, possible MigrationType values are either "home" or "away," indicating if the individual was in their home node or not when the simulation ended. For all other events, the possible values are: air, local, sea, or regional.
Event enum The event triggering the migration information to be reported. Possible values are: STIPreEmigrating, STIPostImmigrating, NonDiseaseDeaths, DiseaseDeaths. Emigrating means the individual is moving, SimulationEnd means the simulation has finished. One row of data will be recorded for each event.
IsInfected boolean Describes whether or not the individual is infected: 0 for not infected, 1 for infected.
Rel_ID integer The unique ID of the relationship that is migrating.
NumCoitalActs integer The total number of coital acts this couple has had within this relationship up to this time.
IsDiscordant boolean Describes whether or not both individuals in a relationship are infected: 0 indicates that the partners are either both infected or both uninfected, 1 indicates that one of the partners is infected and the other is not.
HasMigrated boolean 0 indicates false, 1 indicates that the person identified by IndividualID has completed migrating. Will be true when the event is STIPostImmigrating.
RelationshipType enum The type of relationship whose information is being added to the report. Options are: TRANSITORY, INFORMAL, MARITAL, COMMERCIAL.
RelationshipState enum The state of the relationship. Possible values are:

NORMAL: Both partners are in the same node and can have coital acts.

MIGRATING: The partners are migrating together to a new node.

PAUSED: One of the partners is not in the same node so the couple will pause their coital acts.

TERMINATED: This is when the relationship ends. This value is unlikely to be seen in this report.
PartnerID integer The unique ID of the partner in the relationship with that of IndividualID.
Male_NodeID integer The node that the male of the relationship is in. If the value is zero, then IndividualID is a female and the male's location is unknown. The relationship will be in the PAUSE state.
Female_NodeID integer The node that the female of the relationship is in. If the value is zero, then IndividualID is a male and the female's location is unknown. The relationship will be in the PAUSE state.

Example

The following is an example of a ReportRelationshipMigrationTracking.csv file.

1278 1964 267 52.5321 F 4 2 local STIPreEmigrating 0 84 72 0.1 0.2 MARITAL PAUSED 101 0.3 4.1
1278 1964 267 52.5321 F 2 0 N/A STIPostImmigrating 0 84 72 0 0 MARITAL NORMAL 101 2 2
1279 1964 238 41.2518 F 1 2 local STIPreEmigrating 0 91 130 0 0 INFORMAL PAUSED 263 0 1
1279 1964 238 41.2518 F 2 0 N/A STIPostImmigrating 0 91 130 0 0 INFORMAL PAUSED 263 0 2
1280 1964.01 71 41.5481 M 4 2 local STIPreEmigrating 0 106 35 0 0 MARITAL PAUSED 255 4 0
1280 1964.01 202 36.6187 M 1 4 local STIPreEmigrating 0 166 21 0 0 TRANSITORY PAUSED 58 1 0
1280 1964.01 202 36.6187 M 4 0 N/A STIPostImmigrating 0 166 21 0 0 TRANSITORY PAUSED 58 4 0
1280 1964.01 71 41.5481 M 2 0 N/A STIPostImmigrating 0 106 35 0 0 MARITAL NORMAL 255 2 2
1281 1964.01 316 32.6281 F 4 3 local STIPreEmigrating 0 154 47 0 0 MARITAL PAUSED 20 0 4
1281 1964.01 129 53.1052 F 2 4 local STIPreEmigrating 0 62 141 0 0 MARITAL PAUSED 249 0 2
1281 1964.01 129 53.1052 F 4 0 N/A STIPostImmigrating 0 62 141 0 0 MARITAL PAUSED 249 0 4
1281 1964.01 316 32.6281 F 3 0 N/A STIPostImmigrating 0 154 47 0 0 MARITAL PAUSED 20 0 3
1282 1964.01 164 43.9009 F 2 3 local STIPreEmigrating 0 44 66 0 0 MARITAL NORMAL 248 2 2
1282 1964.01 164 43.9009 F 3 0 N/A STIPostImmigrating 0 44 66 0 0 MARITAL PAUSED 248 0 3
1283 1964.02 26 39.4271 F 3 1 local STIPreEmigrating 0 130 64 0 0 MARITAL PAUSED 187 0 3
1283 1964.02 148 31.3444 M 2 3 local STIPreEmigrating 0 116 48 0 0 INFORMAL NORMAL 63 2 2
1283 1964.02 148 31.3444 M 3 0 N/A STIPostImmigrating 0 116 48 0 0 INFORMAL PAUSED 63 3 0
1283 1964.02 26 39.4271 F 1 0 N/A STIPostImmigrating 0 130 64 0 0 MARITAL PAUSED 187 0 1
1284 1964.02 238 41.2654 F 2 1 local STIPreEmigrating 0 91 130 0 0 INFORMAL PAUSED 263 0 2
1284 1964.02 35 30.2736 F 1 2 local STIPreEmigrating 0 165 9 0 0 INFORMAL PAUSED 117 0 1
1284 1964.02 35 30.2736 F 2 0 N/A STIPostImmigrating 0 165 9 0 0 INFORMAL PAUSED 117 0 2
1284 1964.02 238 41.2654 F 1 0 N/A STIPostImmigrating 0 91 130 0 0 INFORMAL PAUSED 263 0 1
1285 1964.02 129 53.1161 F 4 3 local STIPreEmigrating 0 62 141 0 0 MARITAL PAUSED 249 0 4
1285 1964.02 119 43.9805 F 4 2 local STIPreEmigrating 0 68 98 0 0 MARITAL PAUSED 163 0 4
1285 1964.02 119 43.9805 F 2 0 N/A STIPostImmigrating 0 68 98 0 0 MARITAL PAUSED 163 0 2
1285 1964.02 129 53.1161 F 3 0 N/A STIPostImmigrating 0 62 141 0 0 MARITAL NORMAL 249 3 3
1286 1964.02 168 38.5155 F 4 3 local STIPreEmigrating 0 18 86 0 0 MARITAL PAUSED 160 0 4
1286 1964.02 168 38.5155 F 3 0 N/A STIPostImmigrating 0 18 86 0 0 MARITAL NORMAL 160 3 3
1287 1964.03 248 50.4619 M 2 3 local STIPreEmigrating 0 44 66 0 0 MARITAL PAUSED 164 2 0
1287 1964.03 248 50.4619 M 3 0 N/A STIPostImmigrating 0 44 66 0 0 MARITAL NORMAL 164 3 3
1288 1964.03 277 31.8828 M 4 2 local STIPreEmigrating 0 160 30 0 0 INFORMAL NORMAL 237 4 4
1288 1964.03 67 52.7351 F 2 1 local STIPreEmigrating 0 50 53 0 0 MARITAL PAUSED 89 0 2
1288 1964.03 294 42.8007 F 1 4 local STIPreEmigrating 0 129 101 0 0 MARITAL NORMAL 190 1 1
1288 1964.03 294 42.8007 F 4 0 N/A STIPostImmigrating 0 129 101 0 0 MARITAL PAUSED 190 0 4
1288 1964.03 67 52.7351 F 1 0 N/A STIPostImmigrating 0 50 53 0 0 MARITAL PAUSED 89 0 1
1288 1964.03 277 31.8828 M 2 0 N/A STIPostImmigrating 0 160 30 0 0 INFORMAL PAUSED 237 2 0
1289 1964.03 125 35.7124 F 4 1 local STIPreEmigrating 0 70 120 0 0 MARITAL PAUSED 109 0 4
1289 1964.03 125 35.7124 F 1 0 N/A STIPostImmigrating 0 70 120 0 0 MARITAL NORMAL 109 1 1