emodpy_hiv.reporters.reporters module

class emodpy_hiv.reporters.reporters.ReportNodeDemographics(reporters_object: Reporters, ip_key_to_collect: str | None = None, age_bins: list[float] | None = None, stratify_by_gender: bool = True)

Bases: BuiltInReporter

The node demographics report (ReportNodeDemographics.csv) is a CSV-formatted report that provides population information stratified by node. For each time step, the report will collect data on each node and age bin.

For HIV, see ReportNodeDemographics and for malaria, see ReportNodeDemographics.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• ip_key_to_collect (str) –

  Name of the IndividualProperties Key to stratify the report. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

  Default is None.

• age_bins (list[float]) –

  Age bins (in years) to stratify by, in ascending order.

  Default is None.

• stratify_by_gender (bool) –

  If True, stratify by gender.

  Default: True.

class emodpy_hiv.reporters.reporters.ReportSimulationStats(reporters_object: Reporters)

Bases: BuiltInReporter

Creates the ReportSimulationStats to summarize key simulation statistics.

For more information: HIV’s ReportSimulationStats or Malaria’s ReportSimulationStats

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.ReportHumanMigrationTracking(reporters_object: Reporters)

Bases: BuiltInReporter

The human migration tracking report (ReportHumanMigrationTracking.csv) is a CSV-formatted report that provides details about human travel during simulations. The finished report will provide one line for each surviving individual that migrates during the simulation.

For HIV, see ReportHumanMigrationTracking and for malaria, see ReportHumanMigrationTracking.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.ReportEventCounter(reporters_object: Reporters, event_list: list[str], report_filter: ReportFilter | None = None)

Bases: BuiltInReporter

The event counter report (ReportEventCounter.json) is a JSON-formatted file that keeps track of how many of each individual-level event types occur during a time step. The report produced is similar to the InsetChart.json channel report, where there is one channel for each event defined in the ‘event_list’ parameter. This report only counts events; a similar report, ReportEventRecorder, will provide information about the person at the time of the event.

For HIV, see ReportEventCounter, and for malaria, see ReportEventCounter

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• event_list (list[str]) – List of individual-level events which to count. There will be one channel for each event in the list. For HIV, see Event list and for malaria: Event list for available built-in events, as well as custom events you’ve defined in campaigns.

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_day

  • end_day

  • filename_suffix

  • node_ids

  • min_age_years

  • max_age_years

  • must_have_ip_key_value

  • must_have_intervention

class emodpy_hiv.reporters.reporters.ReportEventRecorder(reporters_object: Reporters, event_list: list[str], individual_properties: list[str] | None = None, property_change_ip_to_record: str | None = None, report_filter: ReportFilter | None = None)

Bases: ConfigReporter

The health events and interventions report (ReportEventRecorder.csv) provides information on each individual’s demographics and health status at the time of an event. Additionally, it is possible to see the value of specific IndividualProperties, as assigned in the demographics file.

For more information, see ReportEventRecorder.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• event_list (list[str]) – The list of individual-level events to include in the output report. See Event list for events already used by EMOD, or add custom events you’re using in campaigns.

• individual_properties (list[str], optional) –

  A list of strings individual property (IP) keys that will be included in the report as applicable to each partner at the start of the relationship. One column will be added to the report for each partner, for each key in the list. For more information, see Individual and node properties.

  Default: None

• property_change_ip_to_record (str, optional) –

  IndividualProperty key string for which recorder will add the PropertyChange event to the list of events that the report is listening to. However, it will only record the events where the property changed the value of this given key. For more information, see Individual and node properties.

  Default: None

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_year

  • end_year

  • node_ids

  • min_age_years

  • max_age_years

  • must_have_ip_key_value

  • must_have_intervention

class emodpy_hiv.reporters.reporters.ReportPluginAgeAtInfection(reporters_object: Reporters)

Bases: BuiltInReporter

Creates ReportPluginAgeAtInfection report to be added to the simulation.

For more information: HIV’s ReportPluginAgeAtInfection or Malaria’s ReportPluginAgeAtInfection

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.ReportPluginAgeAtInfectionHistogram(reporters_object: Reporters, age_bin_upper_edges: list[float] | None = None, reporting_interval: float = 1)

Bases: BuiltInReporter

Creates ReportPluginAgeAtInfectionHistogram report to be added to the simulation.

For more information: HIV’s ReportPluginAgeAtInfectionHistogram or Malaria’s ReportPluginAgeAtInfectionHistogram

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• age_bin_upper_edges (list[float]) – A list of ages (in years) where an individual will count in the upper value bin when their age is between two bins.

• reporting_interval (float) – Repeating time period (in years) for which the data is collected and reported

class emodpy_hiv.reporters.reporters.SqlReport(reporters_object: Reporters, include_health_table: bool = True, include_individual_properties: bool = False, include_infection_data_table: bool = True, report_filter: ReportFilter | None = None)

Bases: BuiltInReporter

The SqlReport outputs epidemiological and transmission data. Because of the quantity and complexity of the data, the report output is a multi-table SQLite relational database (see https://sqlitebrowser.org/). Use the configuration parameters to manage the size of the database.

For more information: HIV’s SqlReport or Malaria’s SqlReport

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• include_health_table (bool) –

  If True, include health-related data in the report.

  Default: True

• include_individual_properties (bool) –

  If True, include individual properties in the report. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

  Default: False

• include_infection_data_table (bool) –

  If True, include infection data in the report.

  Default: True

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_day

  • end_day

class emodpy_hiv.reporters.reporters.ReportNodeEventRecorder(reporters_object: Reporters, event_list: list[str], node_properties_to_record: list[str] | None = None, stats_by_ips: list[str] | None = None)

Bases: ConfigReporter

The Node-level events report (ReportNodeEventRecorder.csv) provides information on node’s population and health status at the time of a node-level event. Additionally, it is possible to break up the population data by specific Node and Individual Properties.

For more information: HIV’s ReportNodeEventRecorder or Malaria’s ReportNodeEventRecorder

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• event_list (list[str]) – The list of node-level events to include in the output report. These would be node-level events you have used in your campaigns.

• node_properties_to_record (list[str], optional) – A list of node property keys, as defined in NodeProperties in the demographics, to be added as additional columns to the ReportNodeEventRecorder.csv output report. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

• stats_by_ips (list[str], optional) – A list of individual property keys, as defined in IndividualProperties in the demographics. For each key in this list, there are two columns added for each value of the key, key::NumIndividuals and key::NumInfected. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

class emodpy_hiv.reporters.reporters.ReportCoordinatorEventRecorder(reporters_object: Reporters, event_list: list[str])

Bases: ConfigReporter

The Coordinator-level events report (ReportCoordinatorEventRecorder.csv) records the event, time, and the coordinator sending out the event.

For more information: HIV’s ReportCoordinatorEventRecorder or Malaria’s ReportCoordinatorEventRecorder

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• event_list (list[str]) – The list of coordinator-level events to include in the output report. These would be coordinator-level events you’ve used in campaigns.

class emodpy_hiv.reporters.reporters.ReportSurveillanceEventRecorder(reporters_object: Reporters, event_list: list[str], stats_by_ips: list[str] | None = None)

Bases: ConfigReporter

The Coordinator-level events report (ReportSurveillanceEventRecorder.csv) for events sent out by a SurveillanceEventCoordinator. The report provides information on node’s population and health status at the time of an event. Additionally, it is possible to break up the population data by specific Node and Individual Properties. Only the nodes that the SurveillanceEventCoordinator listening to will be included in the report.

For more information: HIV’s ReportSurveillanceEventRecorder or Malaria’s ReportSurveillanceEventRecorder

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• event_list (list[str]) – The list of coordinator-level events to include in the output report. These would be coordinator-level events you’ve used in campaigns.

• stats_by_ips (list[str], optional) – A list of individual property keys, as defined in IndividualProperties in the demographics. For each key in this list, there are two columns added for each value of the key, key::NumIndividuals and key::NumInfected. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

class emodpy_hiv.reporters.reporters.InsetChart(reporters_object: Reporters, has_ip: list[str] | None = None, has_interventions: list[str] | None = None, include_pregnancies: bool = False, include_coital_acts: bool = True, event_channels_list: list[str] | None = None)

Bases: InsetChart

The inset chart (InsetChart.json) is an output report that is automatically generated with every simulation. It contains simulation-wide averages, one per time step, for a wide number of data channels. The channels are fully specified by the simulation type and cannot be altered without making changes to the EMOD source code. Python or other tools can be used to create charts out of the information contained in the file.

For more information, see InsetChart

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy

• has_ip (list[str], optional) – A channel is added to InsetChart for each value of each IndividualProperty key provided. The channel name will be HasIP_<Key:Value> and will be the fraction of the population that has that value for that Individual Property Key. For more information, see Individual and node properties. Default: None

• has_interventions (list[str], optional) – A channel is added to InsetChart for each intervention name provided. The channel name will be Has_<InterventionName> and will be the fraction of the population that has that intervention. The intervention_name parameter in the campaigns are the available values for this parameter. Default: None

• include_pregnancies (bool, optional) – If True, channels are added about pregnancies and possible mothers. Default: False

• include_coital_acts (bool, optional) – If True, include channels about the number of coital acts per relationship type per timestep and those using condoms. Default: True

• event_channels_list (list[str], optional) – This is the list of events included in the InsetChart report. If events are specified with this parameter, the InsetChart will include a channel for each event listed. If no events are listed, a ‘Number of Events’ channel will display the total number of all events that occurred during the simulation. See Event list for events already used by EMOD or add custom events you’re using in campaigns. Default: None

class emodpy_hiv.reporters.reporters.SpatialReport(reporters_object: Reporters, spatial_output_channels: list[str])

Bases: ConfigReporter

Creates a separate spatially-distributed data binary (SpatialReport_{Channel_Name}.bin) for every channel listed.

For HIV, see SpatialReport, and for malaria, see SpatialReport

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• spatial_output_channels (list[str]) –

  List of data channels for which to create spatial reports. All the channels are defined in the SpatialReportChannels enum. Please use the enum to define the channels.

  Example:

  SpatialReport(reporters_object=reporters,
                spatial_output_channels=[SpatialReportChannels.Infected,
                                        SpatialReportChannels.Births])
  

class emodpy_hiv.reporters.reporters.ReportHIVByAgeAndGender(reporters_object: Reporters, collect_gender_data: bool = False, collect_age_bins_data: list[float] | None = None, collect_circumcision_data: bool = False, collect_hiv_data: bool = False, collect_hiv_stage_data: bool = False, collect_on_art_data: bool = False, collect_ip_data: list[str] | None = None, collect_intervention_data: list[str] | None = None, collect_targeting_config_data: list[emodpy_hiv.utils.targeting_config.AbstractTargetingConfig] | None = None, add_transmitters: bool = False, stratify_infected_by_cd4: bool = False, event_counter_list: list[str] | None = None, add_relationships: bool = False, add_concordant_relationships: bool = False, reporting_period: float = 182.5, use_old_format: bool = False, report_filter: ReportFilter | None = None)

Bases: ConfigReporter

The age- and gender-stratified HIV report (ReportHIVByAgeAndGender.csv) provides a detailed set of HIV-related statistics, with numerous ways to customize and stratify the output. The report format facilitates further analysis using a pivot table.

Some results, such as population size or number infected, are reported as single ‘snapshots’ at the end of the reporting period. Other values, such as deaths or new infections, are aggregated for the entire reporting period.

For more information, see ReportHIVByAgeAndGender.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• collect_gender_data (bool, optional) –

  When True, the ‘Gender’ column will be added where 0 is for males and 1 for females.

  Default: False

• collect_age_bins_data (list[float], optional) – A list of age bins (values in years) used to stratify the report by age. When this parameter is used, the ‘Age’ column will be added and the reports and will have a row for each bin value. The row will include all individuals whose age is between the value in the bin (inclusive) and the next bin’s value (exclusive). The values between the bins cannot be equal and must be listed in ascending order. Leave the array empty to not stratify the report by age. The maximum number of age bins is 100. Note: setting this will multiply the number of rows in the output report by the number of bins.

• collect_circumcision_data (bool, optional) –

  When True, the ‘IsCircumcised’ column is included in the output report. The report data will be stratified by those who have the MaleCircumcision intervention (1) and those who do not (0). Note: setting this to True will double the number of rows for males in the output report.

  Default: False

• collect_hiv_data (bool, optional) –

  When True, the ‘HasHIV’ column is included in the output report. The report data will be stratified by those individuals who have HIV (1) and those who do not (0). Cannot be used with Report_HIV_ByAgeAndGender_Collect_HIV_Stage_Data. Note: setting this to True doubles the number of rows in the output report.

  Default: False

• collect_hiv_stage_data (bool, optional) –

  When True, the ‘HIV_Stage’ column is included in the output report. The report data will be stratified by HIV Infection Stage (NOT_INFECTED, ACUTE, LATENT, AIDS, ON_ART). Cannot be used with collect_hiv_data or collect_on_art_data. Note: setting this to True multiplies the number of rows in the output report by five.

  Default: False

• collect_on_art_data (bool, optional) –

  When set to True, the ‘On_ART’ column is included in the output report. The report data will be stratified by those individuals who are on ART (1) and those who are not (0). Cannot be used with collect_hiv_stage_data. Note: setting this to True doubles the number of rows in the output report.

  Default: False

• collect_ip_data (list[str], optional) –

  A list of individual property (IP) keys used to stratify the report. A column ‘IP_Key:X’ will be added to the report for each IP listed, and a row for each possible IP Key:Value pair. For more information, see Individual and node properties.

  Default: None

• collect_intervention_data (list[str], optional) –

  A list of interventions used to stratify the report. This allows for reporting on a subset (or all) of the interventions that an individual has been on, of those listed in the intervention_name campaign parameter. Those with the intervention will have a 1 in the column and those without will have 0. Note: this can only be used with interventions that remain with an individual for a period of time, such as VMMC, vaccine/PrEP, or those with a delay state in the cascade of care.

  Default: None

• collect_targeting_config_data (list[AbstractTargetingConfig], optional) –

  Creates a ‘MeetsTargetingConfig_X’ column for each targeting config defined in the list where X is the position of the targeting config in the list. In cell, value 1 indicates that the individuals match the targeting config and 0 indicating that they do not.

  Default: None

• add_transmitters (bool, optional) –

  When True, the ‘Transmitters’ column will be added to the report. It indicates the total number of the individuals in that row who transmitted HIV during this reporting period. This may not add up to the number of new infections in the reporting period if any of the new infections were due to the OutbreakIndividual intervention or maternal transmission.

  Default: False

• stratify_infected_by_cd4 (bool, optional) –

  When True, the number of infected individuals will be segregated into four columns based on CD4 count (‘Infected CD4 Under 200 (Not On ART)’, ‘Infected CD4 200 to 349 (Not On ART)’, ‘Infected CD4 350 to 499 (Not On ART)’, ‘Infected CD4 500 Plus (Not On ART)’) Note: this creates additional polling columns, but not more stratification rows.

  Default: False

• event_counter_list (list[str], optional) –

  A list of individual-level events. A column will be added to the report for each event listed, showing the number of times the event occurred during the reporting for the people in the row. To be counted, the individual must qualify for that row at the time the event occurred, not necessarily at the end of the reporting period (the individual themselves might end up being counted in a different row). See Event list for events already used by EMOD, or add custom events you’re using in campaigns. parameter in config.

  Default: None

• add_relationships (bool, optional) –

  When True, the report will contain data on the population currently in a relationship and ever in a relationship for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL), eight columns total. Additionally, columns containing a sum of individuals in two or more partnerships (Has Concurrent Partners) and a sum of the lifetime number of relationships (Lifetime Partners) will be included.

  Default: False

• add_concordant_relationships (bool, optional) –

  When True, a Concordant column for each relationship type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL) is included in the output report. These contain totals for each relationship of each type where both partners have the same HIV status.

  Default: False

• reporting_period (float, optional) –

  The number of days between records in output report. Note: Due to an old design choice, the reporting_period for his report is halved within EMOD’s code. To keep it consistent with other reporters that use reporting periods, emodpy will automatically multiply this value by 2 before passing it to EMOD. This means the reporting_period you enter here will correctly represent the actual time between report entries, rather than being halved.

  Minimum value: 15 Maximum value: 182,500 Default value: 182.5 (every 6 months)

• use_old_format (bool, optional) –

  When True, data collection is offset by one time step: the first entry includes an extra time step, and subsequent entries occur at reporting_period but remain offset. This is a superseded functionality. When set to False, data is collected as expected - data is collected for and reported every reporting_period.

  Default: False

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_year

  • end_year

class emodpy_hiv.reporters.reporters.ReportRelationshipStart(reporters_object: Reporters, include_hiv_disease_statistics: bool = True, include_other_relationship_statistics: bool = True, individual_properties: list[str] | None = None, report_filter: ReportFilter | None = None)

Bases: ConfigReporter

The relationship formation report (RelationshipStart.csv) provides information about each relationship and its members, evaluated at the time of relationship formation. The report includes the relationship type, start time, scheduled end time, and detailed information about each participant: ID, gender, age, infection status, circumcision status for males, co-infections, number of relationships (active, recent, lifetime), and individual properties. The male in the relationship is indicated on the report as participant ‘A’, and the female as participant ‘B’.

For more information, see RelationshipStart.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• include_hiv_disease_statistics (bool, optional) –

  When True, the report will include information on CD4 count, viral load, disease stage, HIV positivity, and HIV testing results for each partner at the start of the relationship.

  Default: False

• include_other_relationship_statistics (bool, optional) –

  When True, the report will include information on the number of active and lifetime relationships of each type (TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL) for each partner in the relationship, as well as total relationships in the past six month and total lifetime relationships. Additionally, a bitmask column will indicate which types of concurrent relationships are allowed; these are configured using the Concurrency_Configuration parameter in the demographics, see Demographics parameters.

  Default: False

• individual_properties (list[str], optional) – A list of strings individual property (IP) keys that will be included in the report as applicable to each partner at the start of the relationship. One column will be added to the report for each partner, for each key in the list. For more information, see Individual and node properties.

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. To be included into the report, only one of the partners needs to satisfy the field. Valid filtering parameters for this report are:

  • start_year

  • end_year

  • node_ids

  • min_age_years

  • max_age_years

  • must_have_ip_key_value

  • must_have_intervention

class emodpy_hiv.reporters.reporters.ReportCoitalActs(reporters_object: Reporters, relationship_type: RelationshipType | None = None, has_intervention_with_name: list[str] | None = None, individual_properties: list[str] | None = None, partners_with_ip_key_value: list[str] | None = None, report_filter: ReportFilter | None = None)

Bases: ConfigReporter

The coital act report (RelationshipConsummated.csv) provides detailed information about each coital act that occurs during the simulation. The report includes unique identifiers for each coital act and relationship; the relationship type, number of acts, whether a condom was used, and whether transmission occurred; and detailed information about each participant, including age, gender, infection status, circumcision status, co-infection status, and treatment status. Each participant in a relationship is referred to as either participant “A” or participant “B”.

One row of data is returned per coital act, and results are ordered on a per-relationship basis. Note: if a person is engaged in coital acts in multiple relationships during a time step, the order of those acts is unknown, only in which relationship they occurred. Additionally, if a person gets infected during a time step, they cannot re-transmit that infection during the same time step. The report does record during which coital act transmission occurred.

If an uninfected person has coital acts with multiple infected partners during the same time step, all acts with the possibility of transmission are randomly ordered, so that the person has an equal chance of getting infected from any one of their partners. The probability of transmission from any one of these coital acts is still determined by the simulation parameters (number of acts, acquisition multipliers, etc.)

For more information, please see RelationshipConsummated.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• relationship_type (RelationshipType, optional) – A RelationshipType enum indicating the type of relationship the coital act has to occur in to be reported. Options are TRANSITORY, INFORMAL, MARITAL, and COMMERCIAL. Leave empty or None to include all relationship types. Default: None Note: RelationshipType.COUNT is not a valid parameter for this report.

• has_intervention_with_name (list[str], optional) –

  An list of intervention names where a column is added for each name. The column will have a value of 1 if the person has the intervention and 0 if they do not. The intervention_name parameter in the campaigns are the available values for this parameter.

  Default: None

• individual_properties (list[str], optional) – A list of strings individual property (IP) keys that will be included in the report as columns. Each person will have the value of that key in their row. For more information, see Individual and node properties. Default: None

• partners_with_ip_key_value (list[str], optional) –

  A list of strings in format of “Key:Value”, denoting specific IndividualProperty key:value pair. For each IP Key:Value string in the list, two columns will be added - one for each partner indicating the number of their partners for whom that IP Key:Value applies. For more information, see Individual and node properties.

  Default: None

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. To be included into the report, only one of the partners needs to satisfy the field. Valid filtering parameters for this report are:

  • start_year

  • end_year

  • node_ids

  • min_age_years

  • max_age_years

  • must_have_ip_key_value

  • must_have_intervention

class emodpy_hiv.reporters.reporters.ReportRelationshipEnd(reporters_object: Reporters)

Bases: ConfigReporter

The relationship dissolution report (RelationshipEnd.csv) provides detailed information about each relationship and its members, evaluated at the time of relationship dissolution. The report includes the relationship id, relationship type, start time, scheduled end time, actual end time (which may differ from the scheduled end time, for instance, due to the death of a partner), and information about each participant. The relationship id is unique to each relationship and is the same across all reports that reference relationships: ReportRelationshipStart, ReportTransmission, and the ReportCoitalActs.

For more information, please see RelationshipEnd.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy

class emodpy_hiv.reporters.reporters.ReportTransmission(reporters_object: Reporters)

Bases: ConfigReporter

The HIV relationship transmission report (TransmissionReport.csv) provides detailed information about each transmission event and relationship members, evaluated at the time of disease transmission within the relationship. It includes the time/date of transmission and information about the transmitter and recipient, including: age, gender, current and lifetime number of relationships, infection stage, circumcision status for males, co-infections, and disease-specific biomarkers, if applicable.

For more information, see TransmissionReport.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy

class emodpy_hiv.reporters.reporters.ReportHIVART(reporters_object: Reporters)

Bases: ConfigReporter

The ART initiation and discontinuation report (ReportHIVART.csv) provides information on individuals at time of ART initiation and discontinuation, including ID, age, gender, and CD4 count at ART initiation.

For more information, see ReportHIVART.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy

class emodpy_hiv.reporters.reporters.ReportHIVInfection(reporters_object: Reporters, report_filter: ReportFilter | None = None)

Bases: ConfigReporter

The HIV disease progression report (ReportHIVInfection.csv) provides information on each individual’s disease state at each time step, including age, gender, CD4 count, survival prognosis, ART status, and factors impacting transmission and acquisition.

For more information, see ReportHIVInfection.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_year

  • end_year

class emodpy_hiv.reporters.reporters.ReportHIVMortality(reporters_object: Reporters)

Bases: ConfigReporter

The HIV mortality report (HIVMortality.csv) provides information about individuals at the time of their death, including disease status, CD4 count, medical history, and relationship history.

For more information, see HIVMortality.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy

class emodpy_hiv.reporters.reporters.ReportRelationshipMigrationTracking(reporters_object: Reporters, report_filter: ReportFilter | None = None)

Bases: BuiltInReporter

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.

For more information, see ReportRelationshipMigrationTracking.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_year

  • end_year

  • filename_suffix

  • node_ids

  • min_age_years

  • max_age_years

  • must_have_ip_key_value

  • must_have_intervention

class emodpy_hiv.reporters.reporters.ReportPfaQueues(reporters_object: Reporters)

Bases: BuiltInReporter

The pair forming algorithm (PFA) queues report (ReportPfaQueues.csv) provides data to analyze the relationship formation process and evaluate who is left unpaired at each stage.

The report includes several key columns: Time, which represents the simulation day when the data is recorded, and NodeID, which specifies the external ID of the simulation node. Additionally, the columns labeled <Before/After> (e.g., TRANSITORY_M_Before_20) indicate the count of individuals in specific bins at different stages of the process. The “Before” stage represents the moment just before individuals are paired, capturing those who have entered the PFA and are eligible for relationship formation based on the formation rate. The “After” stage reflects the individuals remaining in the PFA after pairing, who will wait until the next time step to enter a relationship of the specified type.

For more information: ReportPfaQueues

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.ReportRelationshipCensus(reporters_object: Reporters, report_filename: str = 'ReportRelationshipCensus.csv', reporting_interval_years: float = 1, report_filter: ReportFilter | None = None)

Bases: BuiltInReporter

The relationship census report (ReportRelationshipCensus.csv) is a CSV-formatted report that extracts relationship numbers for each person during each taking of the census. The census is a one-day event collecting data for that person as of that day.

For more information, see ReportRelationshipCensus.

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• report_filename – The name for the file of the generated report including file extension

• reporting_interval_years – Number of years between census-taking.

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_year

  • end_year

class emodpy_hiv.reporters.reporters.ReportFilter(start_day: float | None = None, end_day: float | None = None, start_year: float | None = None, end_year: float | None = None, filename_suffix: str = '', node_ids: list[int] | None = None, min_age_years: float | None = None, max_age_years: float | None = None, must_have_ip_key_value: str = '', must_have_intervention: str = '')

Bases: object

This class is designed to configure common filter parameters for generating simulation reports. It provides a range of options to specify the time period, nodes, and individual criteria for data collection.

Parameters:

• start_day (float, optional) –

  • The day of the simulation to start collecting data.

  • Minimum value: 0

  • Maximum value: 3.40282e+38

  • Default value: 0

• end_day (float, optional) –

  • The day of simulation to stop collecting data.

  • Minimum value: 0

  • Maximum value: 3.40282e+38

  • Default value: 3.40282e+38

• start_year (float, optional) –

  • This only applies to HIV_SIM

  • The simulation time in years to start collecting data. Use decimals to start collecting data not at the beginning of the year.

  • Minimum value: 1900

  • Maximum value: 2200

  • Default value: 1900

• end_year (float, optional) –

  • This only applies to HIV_SIM

  • The simulation time in years to stop collecting data. Use decimals to start collecting data not at the beginning of the year.

  • Minimum value: 1900

  • Maximum value: 2200

  • Default value: 2200

• filename_suffix (str, optional) –

  • Augments the filename of the report. This allows you to generate multiple reports for distinguishing among them.

  • Default value: “”

• node_ids (list[int], optional) –

  • A list of nodes ids from which to collect data for the report. Use empty array or None to collect data from all nodes. Node ids must be integers.

  • Minimum value: 0

  • Maximum value: 3.40282e+38

  • Default value: None

• min_age_years (float, optional) –

  • Minimum age, in years, that a person can be to be included in the report.

  • Minimum value: 0

  • Maximum value: 1000

  • Default value: 0

• max_age_years (float, optional) –

  • Maximum age, in years, that a person can be to be included in the report.

  • Minimum value: 0

  • Maximum value: 1000

  • Default value: 1000

• must_have_ip_key_value (str, optional) –

  • A string formatted as “Key:Value”, representing a specific IndividualProperty key-value pair required for an individual to be included in the report. For HIV_SIM, when reporting on relationships, at least one partner must have this property for the relationship to be included in the report. If set to an empty string or None, no filtering is applied, and all individuals are included. For malaria, see Individual and node properties and for HIV, see Individual and node properties.

  • Default value: “”

• must_have_intervention (str, optional) –

  • The intervention_name parameter in the campaigns are the available values for this parameter. that an individual must have to be included in the report. For HIV_SIM, at least one partner must have this intervention for inclusion when reporting on relationships. If set to an empty string or None, no filtering is applied, and all individuals are included.

  • Default value: “”

class emodpy_hiv.reporters.reporters.DemographicsReport(reporters_object: Reporters)

Bases: ConfigReporter

BinnedReport.json and DemographicsSummary.json are both generated by the DemographicsReport.

The demographic summary output report (DemographicsSummary.json) is a JSON-formatted file with the demographic channel output results of the simulation, consisting of simulation-wide averages by time step. The format is identical to the inset chart output report, except the channels reflect demographic categories, such as gender ratio.

The binned output report (BinnedReport.json) is a JSON-formatted file where the channel data has been sorted into age bins. It is very similar to an inset chart, however, with the binned report all channels are broken down into sub-channels (bins) based on age. For example, instead of having a single prevalence channel, you might have prevalence in the ‘0-3 years old bin’ and the ‘4-6 years old bin’, and so forth.

For HIV, see DemographicsSummary and BinnedReport, and for malaria, see DemographicsSummary and BinnedReport.

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.PropertyReport(reporters_object: Reporters)

Bases: ConfigReporter

The property output report (PropertyReport.json) is a JSON-formatted file with the channel output results of the simulation, defined by the groups set up using IndividualProperties in the demographics file. See IndividualProperties for more information. The report contains the count of individuals with each possible Individual Property (IP) key-value combination. The < channel-title > tells you the statistic and property that are being counted. For example, it allows you to compare disease deaths for people in the high risk group versus the low risk group.

For HIV, see PropertyReport and for malaria, see

PropertyReport

Parameters:

reporters_object (Reporters) – The reporters object given by the emodpy.

class emodpy_hiv.reporters.reporters.ReportInfectionDuration(reporters_object: Reporters, report_filter: ReportFilter | None = None)

Bases: BuiltInReporter

The infection duration report (ReportInfectionDuration.csv)provides one line of information about an infection that has just cleared. It tells you who had the infection and how long they had it.

For more information: HIV’s ReportInfectionDuration or Malaria’s ReportInfectionDuration

Parameters:

• reporters_object (Reporters) – The reporters object given by the emodpy.

• report_filter (ReportFilter, optional) –

  Common report filtering parameters. Valid filtering parameters for this report are:

  • start_day

  • end_day

class emodpy_hiv.reporters.reporters.SpatialReportChannels(value)

Bases: StrEnum

An enumeration.

Air_Temperature = 'Air_Temperature'

Births = 'Births'

Campaign_Cost = 'Campaign_Cost'

Disease_Deaths = 'Disease_Deaths'

Human_Infectious_Reservoir = 'Human_Infectious_Reservoir'

Infected = 'Infected'

New_Infections = 'New_Infections'

New_Reported_Infections = 'New_Reported_Infections'

Population = 'Population'

Prevalence = 'Prevalence'

class emodpy_hiv.reporters.reporters.RelationshipType(value)

Bases: StrEnum

An enumeration.

TRANSITORY = 'TRANSITORY'

INFORMAL = 'INFORMAL'

MARITAL = 'MARITAL'

COMMERCIAL = 'COMMERCIAL'

COUNT = 'COUNT'