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¶