emodpy_hiv.demographics.hiv_demographics module#

This module contains the classes and functions for creating demographics files for HIV simulations. For more information on EMOD demographics files, see Demographics file.

class emodpy_hiv.demographics.hiv_demographics.HIVDemographics(nodes: List[HIVNode], default_society_template: str | None = None)[source]#

Bases: Demographics

property raw#
set_fertility(path_to_csv: str, node_ids: List[int] | None = None) → None[source]#

Set fertility based on data to the selected node(s). Simulation shall consist of individual pregnancies with rates by woman’s age and year-of-simulation using data from provided csv. Bilinear interpolation is performed between supplied data points.

Parameters:

  • path_to_csv – path to csv file to load data from

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

set_mortality(file_male: str, file_female: str, node_ids: List[int] | None = None, interval_fit: List[int | float] | None = None, which_point: str = 'mid', predict_horizon: int | float = 2050, csv_out: bool = False, results_scale_factor: float = 0.0027397260273972603) → None[source]#

Adds male and female non-disease-mortality to the selected node(s). Non-disease-mortality is estimated using the supplied raw data and arguments.

Parameters:

  • file_male – path to csv file to load raw male data from

  • file_female – path to csv file to load raw female data from

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

  • interval_fit – A list of two years, [start, end] , defining a period of used as a ‘non-disease-timeframe’ during the non-disease-mortality calculation

  • which_point – controls mapping of supplied timeframes to ‘start’, ‘end’, or ‘mid’-points of the timeframes

  • predict_horizon – mortality will be computed and set through this specified year

  • csv_out – Writes out diagnostic files if set to True

  • results_scale_factor – Daily data conversion factor: supplied_mortality * factor = daily_mortality

Returns:

None

set_concurrency_params_by_type_and_risk(relationship_type: str, risk_group: str, max_simul_rels_male: float | None = None, max_simul_rels_female: float | None = None, prob_xtra_rel_male: float | None = None, prob_xtra_rel_female: float | None = None, node_ids: List[int] | None = None) → None[source]#

Set concurrent relationship formation parameters for a given relationship type, risk group, and node(s).

Only non-None values will be updated.

Each agent updates their max values and their ability to have extra relationships when they change nodes/locations or change their Risk IP value.

Notes on maximums:

  • A max relationships parameter can be set to 2+, but if probability of extra is zero, an agent will never have more than one relationship of the given type.

  • fractional max relationship parameters are probabilistically rounded up or down per agent. E.g., max relationships of 2.3 implies agents have a (70%, 30%) chance of getting a maximum of (2, 3), respectively.

Note on probabilities:

  • These probabilities apply to agents currently with at least ONE relationship of the given type seeking an additional such relationship.

Parameters:

  • relationship_type – Relationship type to update: “COMMERCIAL”, “MARITAL”, “INFORMAL” or “TRANSITORY”

  • risk_group – risk group to set concurrency parameters for. “HIGH”, “MEDIUM”, or “LOW”

  • max_simul_rels_male – Sets the maximum simultaneous relationships of the given relationship_type for males in the given risk_group.

  • max_simul_rels_female – Sets the maximum simultaneous relationships of the given relationship_type for females in the given risk_group.

  • prob_xtra_rel_male – The probability of a male receiving a flag that allows him to seek additional relationships while currently in another relationship.

  • prob_xtra_rel_female – The probability of a female receiving a flag that allows her to seek additional relationships while currently in another relationship.

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

set_pair_formation_parameters(relationship_type: str, formation_rate: float | None = None, assortivity_matrix: List[List[float]] | None = None, node_ids: List[int] | None = None) → None[source]#

Sets pair formation parameters for the specified relationship type and node(s).

Only non-None values will be updated.

Parameters:

  • relationship_type – Relationship type to update: “COMMERCIAL”, “MARITAL”, “INFORMAL” or “TRANSITORY”

  • assortivity_matrix – 3x3 row-major matrix of assortivity values, row represents male, column represents female. E.g. matrix[male_index][female_index] This matrix defines the tendency for a man of a particular Risk group to select a woman based on her Risk group (LOW/MEDIUM/HIGH male selecting LOW/MEDIUM/HIGH female -> 3x3 matrix).

  • formation_rate – The number of new relationships per day for this relationship type that an individual will start. This can be changed during a simulation via a RelationshipFormationRateChanger intervention.

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

set_relationship_parameters(relationship_type: str, coital_act_rate: float | None = None, condom_usage_min: float | None = None, condom_usage_mid: float | None = None, condom_usage_max: float | None = None, condom_usage_rate: float | None = None, duration_scale: float | None = None, duration_heterogeneity: float | None = None, node_ids: List[int] | None = None) → None[source]#

Sets relationship parameters for the specified relationship type and node(s).

Only non-None values will be updated.

Parameters:

  • relationship_type – Relationship type to update: “COMMERCIAL”, “MARITAL”, “INFORMAL” or “TRANSITORY”

  • coital_act_rate – Sets the per-day coital act rate for the specified relationship type. This can be changed during a simulation via a CoitalActRateChanger intervention.

  • condom_usage_min – minimum condom usage probability (pre-inflection point). All four of these condom usage parameters can be changed during a simulation via a CondomUsageProbabilityChanger intervention.

  • condom_usage_mid – inflection point in condom usage (a year)

  • condom_usage_max – maximum condom usage probability (post-inflection point)

  • condom_usage_rate – slope of condom usage at inflection point

  • duration_scale – weibull distributed relationship duration value (Lambda)

  • duration_heterogeneity – weibull distributed relationship heterogeneity value (1/Kappa)

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

add_or_update_initial_risk_distribution(distribution: List[float], node_ids: List[int] | None = None) → None[source]#

Adds the Risk individual property with specified initial distribution to the specified node(s).

Parameters:

  • distribution – a list of three floats that sum to 1 corresponding to distribution of Risk in this order: ‘LOW’, ‘MEDIUM’, ‘HIGH’

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

add_or_update_initial_cascade_state_distribution(distribution: List[float], node_ids: List[int] | None = None) → None[source]#

Adds the CascadeState individual property with specified initial distribution to the specified node(s).

Parameters:

  • distribution – a list of fourteen floats that sum to 1 corresponding to distribution of CascadeState in this order: ‘’, ‘ARTStaging’, ‘ARTStagingDiagnosticTest’, ‘LinkingToART’, ‘LinkingToPreART’, ‘OnART’, ‘OnPreART’, ‘HCTTestingLoop’, ‘HCTUptakeAtDebut’, ‘HCTUptakePostDebut’, ‘TestingOnANC’, ‘TestingOnChild6w’, ‘TestingOnSymptomatic’, ‘LostForever’

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

add_or_update_initial_health_care_accessibility_distribution(distribution: List[float], node_ids: List[int] | None = None) → None[source]#
Adds the (health care) Accessibility individual property with specified initial distribution to the specified

node(s).

Parameters:

  • distribution – a list of three floats that sum to 1 corresponding to distribution of Accessibility in this order: ‘Yes’, ‘No’

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

SetAgeDistribution(distribution: AgeDistribution, node_ids: List[int] | None = None) → None[source]#

Set the default age distribution for the specified node(s).

Parameters:

  • distribution – age distribution information to set.

  • node_ids – the id(s) of node(s) to apply changes to. None or 0 refers to the Default node.

Returns:

None

AddIndividualPropertyAndHINT(Property: str, Values: List[str], InitialDistribution: List[float] | None = None, TransmissionMatrix: List[List[float]] | None = None, Transitions: List | None = None, node_ids: List[int] | None = None, overwrite_existing: bool = False) → None[source]#

Add Individual Properties, including an optional HINT configuration matrix.

Individual properties act as ‘labels’ on model agents that can be used for identifying and targeting subpopulations in campaign elements and reports. E.g. model agents may be given a property (‘Accessibility’) that labels them as either having access to health care (value: ‘Yes’) or not (value: ‘No’).

Property-based heterogeneous disease transmission (HINT) is available for generic, environmental, typhoid, airborne, or TBHIV simulations as other simulation types have parameters for modeling the heterogeneity of transmission. By default, transmission is assumed to occur homogeneously among the population within a node.

Note: EMOD requires individual property key and values (Property and Values args) to be the same across all

nodes. The individual distributions of individual properties (InitialDistribution) can vary acros nodes.

Documentation of individual properties and HINT:

https://docs.idmod.org/projects/emod-generic/en/latest/model-properties.html https://docs.idmod.org/projects/emod-generic/en/latest/model-hint.html

Parameters:

  • Property – a new individual property key to add (if property already exists an exception is raised unless overwrite_existing is True).

  • Values – the valid values of the new property key

  • InitialDistribution – The fractional initial distribution of each valid Values entry. Order must match Values argument.

  • TransmissionMatrix – HINT transmission matrix.

  • node_ids – The node ids to apply changes to. None or 0 means the ‘Defaults’ node.

  • overwrite_existing – Determines if an error is thrown if the IP is found pre-existing at a specified node. False: throw exception. True: overwrite the existing property.

Returns:

None

to_dict()[source]#
classmethod from_population_dataframe(df: DataFrame, default_society_template: str = None) → __class__[source]#

Loads per-node population information from a formatted pandas DataFrame object into HIVNode objects, returning an HIVDemographics object containing them.

Expected DataFrame format:

node_id,name,population 1,Province1,1000 2,Province2,2500 …

Parameters:

  • df – data for initializing the nodes of an

  • default_society_template – society template name for loading initial society information. Will apply to the Default node.

Returns:

an HIVDemographics object

classmethod from_template_node(lat: float = 0, lon: float = 0, pop: float = 1000000.0, name: str = 'node1', forced_id: int = 1, default_society_template: str = None) → __class__[source]#

Creates a single-node HIVDemographics object from the supplied parameters

Parameters:

  • lat – Latitude of the centroid of the node to create.

  • lon – Longitude of the centroid of the node to create.

  • pop – Human population of the node.

  • name – The name of the node. This may be a characteristic of the node, such as “rural” or “urban”, or an identifying feature or value.

  • forced_id – The node ID for the single node.

  • default_society_template – society template name for loading initial society information. Will apply to the Default node.

Returns:

An HIVDemographics object

classmethod from_pop_csv()[source]#

This method of building demographics is not available for HIVDemographics

classmethod from_params()[source]#

This method of building demographics is not available for HIVDemographics