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 (see the example charts provided at the end of this page.)

Configuration#

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

Parameter

Data type

Min

Max

Default

Description

Enable_Default_Reporting

boolean

NA

NA

1

Set this to 1 (default value) to generate the report.

Report_HIV_Event_Channels_List

array of strings

NA

NA

[]

The list of events to be included in the report. For each event specified with this parameter, one channel will be added to the report. See Event list for possible values. If no events are listed, a ‘Number of Events’ channel will be included on the report and display the total number of all events that occurred during the simulation.

Inset_Chart_Include_Coital_Acts

boolean

NA

NA

0

When set to 1, the report will include channels about the number of coital acts per relationship type per day—in total, and those using condoms (eight channels added).

Inset_Chart_Has_Interventions

array of strings

NA

NA

[]

A list of interventions to be included in the report. For each intervention listed, one channel is added to the report showing the fraction of the population that has that intervention at that time step. Note: the values specified here must match the Intervention_Name parameters listed in the campaign.json file. See Individual-level interventions for information on configuring these parameters.

Inset_Chart_Has_IP

array of strings

NA

NA

[]

A list of individual property (IP) keys to be included in the report. For each value of each IP key provided, one channel is added to the report showing the fraction of the population with that Key:Value pair, at that time step (for example, the fractions in Risk:LOW, Risk:MEDIUM, and Risk:HIGH). See Individual and node properties for additional information on configuring IPs.

Inset_Chart_Include_Pregnancies

boolean

NA

NA

0

If set to 1, three channels are included in the report showing counts of new pregnancies, current pregnancies, and possible mothers at each time step.

{
    "Enable_Default_Reporting": 1,
    "Report_HIV_Event_Channels_List": ["NewInfectionEvent", "HIVNeedsHIVTest", "HIVPositiveHIVTest"],
    "Inset_Chart_Coital_Acts": 1,
    "Inset_Chart_Has_Interventions": ["PrEP"],
    "Inset_Chart_Has_IP": ["InterventionStatus"],
    "Inset_Chart_Include_Pregnancies": 1
}

Output file data#

Headers#

When running HIV simulations, the header section will contain the following parameters.

Parameter

Data type

Description

DateTime

string

The time stamp indicating when the report was generated.

DTK_Version

string

The version of EMOD used.

Report_Type

string

The type of output report.

Report_Version

string

The format version of the report.

Start_Time

integer

The time in days when the simulation begins.

Simulation_Timestep

integer

The number of days in each time step.

Timesteps

integer

The number of time steps in the simulation.

Channels

integer

The number of channels in the simulation.

Base_Year

float

The absolute time in years when the simulation begins. Determined by the Base_Year parameter in the config.json file.

Channels#

When running HIV simulations, the following channels are included in the InsetChart.json file. For channels related to the HIV stage (latent, acute, AIDS), these definitions are described in more detail in Intrahost dynamics and HIV biology.

Channel

Description

Active COMMERCIAL Relationships

The current number of commercial relationships.

Active INFORMAL Relationships

The current number of informal relationships.

Active MARITAL Relationships

The current number of marital relationships.

Active TRANSITORY Relationships

The current number of transitory relationships.

Births

The live births cumulative up to that day.

Campaign Cost

The cost of campaigns cumulative up to that day (set by the Cost_To_Consumer parameter).

Coital Acts Using Condoms-COMMERCIAL

Average number of coital acts using condoms per commercial relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-INFORMAL

Average number of coital acts using condoms per informal relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-MARITAL

Average number of coital acts using condoms per marital relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts Using Condoms-TRANSITORY

Average number of coital acts using condoms per transitory relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-COMMERCIAL

Average number of coital acts per commercial relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-INFORMAL

Average number of coital acts per informal relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-MARITAL

Average number of coital acts per marital relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Coital Acts-TRANSITORY

Average number of coital acts per transitory relationship per time step. Channel appears when the parameter Inset_Chart_Include_Coital_Acts is set to 1.

Disease Deaths

The number of individuals whose death is attributed to HIV/AIDS, cumulative up to that day.

Fraction of New Infections From Rels Outside PFA

The fraction of the total new infections that occurred in relationships created via the StartNewRelationship intervention, rather than the Pair Forming Algorithm (PFA).

Infected

The fraction of the population currently infected.

New Infections

The number of individuals that got infected on that day.

Newly Symptomatic

The number individuals that became symptomatic on that day.

Num Rels Outside PFA

The count of relationships that were created via the StartNewRelationship intervention, rather than the Pair Forming Algorithm (PFA).

Number of (treated) Individuals with AIDS

The number of people who have AIDS but are on ART.

Number of (untreated) Individuals with AIDS

The number of individuals not on ART with AIDS.

Number of (untreated) Individuals with Acute HIV

The number of individuals not on ART with acute HIV.

Number of (untreated) Individuals with Latent HIV

The number of individuals not on ART with latent HIV.

Number of ART dropouts (cumulative)

The number of individuals who started and dropped ART, cumulative up to that day.

Number of Circumcised Males

The number of male individuals that are circumcised via the MaleCircumcision intervention.

Number of Events

The total number of events (births, new infections, etc.) cumulative up to that day.

Number of Individuals Ever in a Relationship

The number of individuals who have ever been in a relationship cumulative up to that day.

Number of Individuals HIV+ w/ CD4 < 200 (non-ART)

The number of individuals who are HIV+ with CD4 count less than 200 and NOT on ART on that day.

Number of Individuals HIV+ w/ CD4 < 200 (on-ART)

The number of individuals who are HIV+ with CD4 count less than 200 and ON ART on that day.

Number of Individuals HIV+ w/ CD4 >= 200 (non-ART)

The number of individuals who are HIV+ with CD4 count greater than 200 and NOT on ART on that day.

Number of Individuals HIV+ w/ CD4 >= 200 (on-ART)

The number of individuals who are HIV+ with CD4 count greater than 200 and ON ART on that day.

Number of Individuals on ART

The total number of individuals on ART on that day.

Paired People

The number of individuals currently in any type of relationship.

Post-Debut Population

The number of individuals that are sexually active.

Prevalence (Females, 15-49)

The fraction of infected individuals in the population of females 15-49.

Prevalence (Males, 15-49)

The fraction of infected individuals in the population of males 15-49.

Prevalence among Sexually Active

The fraction of infected individuals in the post-debut adult population.

Single Post-Debut Men

The number of sexually active males who are currently not in a relationship.

Single Post-Debut Women

The number of sexually active females who are currently not in a relationship.

Statistical Population

The total number of individuals in the simulation on that day.

Symptomatic Population

The total number of symptomatic HIV+ individuals.

Number of Events

If no events are listed in the Report_HIV_Event_Channels_List parameter, this channel will appear in the report, showing the total count of all events that occurred at each time step.

<Event Name>

For each even name listed in the Report_HIV_Event_Channels_List parameter, there will be a corresponding <Event Name> channel in the report, showing the count of those events at each time step. The Number of Events channel will no longer be included in the report.

Has_<Intervention Name>

For each intervention name listed in the Inset_Chart_Has_Interventions parameter, there will be a corresponding Has_<Intervention Name> channel in the report, showing counts of people that have at least one of the named interventions. Note: the intervention names in the list are not checked for accuracy; errors will result in all zeros being returned for that channel. Verify that each intervention name listed in this parameter is defined in the campaign file via the Intervention_Name parameter.

HasIP_<Key:Value>

For each IP key listed in the Inset_Chart_Has_IP parameter, corresponding HasIP_<Key:Value> channels will be added to the report, showing the fraction of people with that IP Key:Value pair, at that time step (one channel for each value of each IP Key). For a given IP, the fractions in each of its value channels should add up to one (1) at each time step.

Possible Mothers

Total number of women that could possibly be mothers (age is between 14 and 45) at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.

New Pregnancies

Total number of women that became pregnant at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.

Currently Pregnant

Total number of women that are currently pregnant at each time step. Channel appears when the parameter Inset_Chart_Include_Pregnancies is set to 1.

Example#

The following is an example of an HIV-specific InsetChart.json.

{
    "Header": {
        "DateTime": "Tue Feb 14 13:29:43 2023",
        "DTK_Version": "0 unknown-branch (unknown) Feb  3 2023 09:00:54",
        "Report_Type": "InsetChart",
        "Report_Version": "3.2",
        "Start_Time": 0,
        "Simulation_Timestep": 1,
        "Timesteps": 8,
        "Channels": 42,
        "Base_Year": 1995
    },
    "Channels": {
        "Active COMMERCIAL Relationships": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Active INFORMAL Relationships": {
            "Units": "Relationships",
            "Data": [4, 17, 27, 38, 43, 50, 57, 64]
        },
        "Active MARITAL Relationships": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Active TRANSITORY Relationships": {
            "Units": "Relationships",
            "Data": [3, 14, 35, 45, 48, 57, 65, 73]
        },
        "Births": {
            "Units": "Births",
            "Data": [1, 1, 2, 3, 4, 7, 9, 12]
        },
        "Campaign Cost": {
            "Units": "USD",
            "Data": [4, 4600, 11049, 11062, 11087, 11116, 11139, 11159]
        },
        "Coital Acts Using Condoms-COMMERCIAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts Using Condoms-INFORMAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0.0588235296309, 0, 0.0526315793395, 0.02325581386685, 0.0599999986589, 0.1228070184588, 0.109375]
        },
        "Coital Acts Using Condoms-MARITAL": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts Using Condoms-TRANSITORY": {
            "Units": "Avg # Acts Per Relationship Using Condoms",
            "Data": [0.3333333432674, 0.1428571492434, 0.0857142880559, 0.02222222276032, 0.02083333395422, 0.0526315793395, 0.04615384712815, 0.01369863003492]
        },
        "Coital Acts-COMMERCIAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts-INFORMAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [1, 0.8235294222832, 0.629629611969, 0.5526315569878, 0.5348837375641, 0.5199999809265, 0.3508771955967, 0.421875]
        },
        "Coital Acts-MARITAL": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Coital Acts-TRANSITORY": {
            "Units": "Avg # Acts Per Relationship",
            "Data": [1, 0.9285714030266, 0.7428571581841, 0.4888888895512, 0.4583333432674, 0.5438596606255, 0.3692307770252, 0.424657523632]
        },
        "Disease Deaths": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 82]
        },
        "Fraction of New Infections From Rels Outside PFA": {
            "Units": "Fraction",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Infected": {
            "Units": "Infected",
            "Data": [0, 0.4988502562046, 0.4988501667976, 0.4988322257996, 0.4988143146038, 0.4988682568073, 0.4988504052162, 0.4988145828247]
        },
        "New Infections": {
            "Units": "",
            "Data": [0, 13884, 0, 0, 1, 1, 1, 1]
        },
        "Newly Symptomatic": {
            "Units": "",
            "Data": [0, 0, 2874, 2, 4, 6, 3, 4]
        },
        "Num Rels Outside PFA": {
            "Units": "Relationships",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (treated) Individuals with AIDS": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (untreated) Individuals with AIDS": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of (untreated) Individuals with Acute HIV": {
            "Units": "",
            "Data": [0, 13884, 13883, 13883, 13884, 13885, 13886, 13887]
        },
        "Number of (untreated) Individuals with Latent HIV": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of ART dropouts (cumulative)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Circumcised Males": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Events": {
            "Units": "",
            "Data": [2343, 46758, 11359, 2274, 2230, 2409, 2145, 2352]
        },
        "Number of Individuals Ever in a Relationship": {
            "Units": "",
            "Data": [14, 62, 126, 174, 204, 246, 286, 328]
        },
        "Number of Individuals HIV+ w/ CD4 < 200 (non-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 93, 119, 143, 164]
        },
        "Number of Individuals HIV+ w/ CD4 < 200 (on-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Individuals HIV+ w/ CD4 >= 200 (non-ART)": {
            "Units": "",
            "Data": [0, 13884, 13883, 13883, 13791, 13766, 13743, 13723]
        },
        "Number of Individuals HIV+ w/ CD4 >= 200 (on-ART)": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Number of Individuals on ART": {
            "Units": "",
            "Data": [0, 0, 0, 0, 0, 0, 0, 0]
        },
        "Paired People": {
            "Units": "People",
            "Data": [14, 62, 124, 166, 182, 214, 244, 274]
        },
        "Post-Debut Population": {
            "Units": "",
            "Data": [15821, 15820, 15821, 15823, 15824, 15825, 15826, 15827]
        },
        "Prevalence (Females, 15-49)": {
            "Units": "",
            "Data": [0, 0.5059130787849, 0.5059130787849, 0.5057594776154, 0.5057594776154, 0.5057594776154, 0.5058372020721, 0.5057594776154]
        },
        "Prevalence (Males, 15-49)": {
            "Units": "",
            "Data": [0, 0.4944348633289, 0.4945916235447, 0.4945123791695, 0.4948275983334, 0.4946708381176, 0.4946725070477, 0.4947500526905]
        },
        "Prevalence among Sexually Active": {
            "Units": "",
            "Data": [0, 0.5322580933571, 0.5476190447807, 0.5114942789078, 0.504901945591, 0.4959349632263, 0.493007004261, 0.4908536672592]
        },
        "Single Post-Debut Men": {
            "Units": "People",
            "Data": [7642, 7618, 7588, 7568, 7561, 7545, 7530, 7515]
        },
        "Single Post-Debut Women": {
            "Units": "People",
            "Data": [8165, 8140, 8109, 8089, 8081, 8066, 8052, 8038]
        },
        "Statistical Population": {
            "Units": "Population",
            "Data": [27832, 27832, 27830, 27831, 27832, 27833, 27836, 27838]
        },
        "Symptomatic Population": {
            "Units": "",
            "Data": [0, 0, 2874, 2876, 2880, 2886, 2889, 2893]
        }
    }
}
../_images/HIVInsetChart-Example.png

Example of plots created from HIV-specific InsetChart data#