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