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.

Time	Year	IndividualID	AgeYears	Gender	From_NodeID	To_NodeID	MigrationType	Event	IsInfected	Rel_ID	NumCoitalActs	IsDiscordant	HasMigrated	RelationshipType	RelationshipState	PartnerID	Male_NodeID	Female_NodeID
1278	1964	267	52.5321	F	4	2	local	STIPreEmigrating	0	84	72	0	0	MARITAL	PAUSED	101	0	4
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