Skip to content

08. Analyzers

Jump to bottom
Nao Yamamoto edited this page Jul 1, 2026 · 2 revisions

Analyzers are Starsim modules that track simulation outcomes during runtime. They collect, aggregate, and store information about agents and their health, service use, intervention exposure, and social determinants over time — enabling post-simulation analysis, plotting, and cost-effectiveness evaluation.

Source code: mighti/analyzers/

Preferred import style:

mi.analyzers.PrevalenceAnalyzer_HIV(...)
# or via compatibility shim: mi.PrevalenceAnalyzer_HIV(...)

Overview

Analyzer Status Tracks Source file
DeathsByAgeSexAnalyzer Implemented Deaths by age/sex; infant deaths analyzer_core.py
AgeSexMxAnalyzer Implemented Per-step exposure and deaths → realized m(x) analyzer_core.py
SurvivorshipAnalyzer Implemented Cohort survivorship l(x) by sex analyzer_core.py
ConditionAtDeathAnalyzer Implemented Agent-level deaths with condition flags and YLL analyzer_core.py
CauseOfDeathYLLAnalyzer Implemented Deaths with cause labels + YLL vs reference e(x) analyzer_core.py
PrevalenceAnalyzer Implemented General prevalence by age/sex analyzer_prevalence.py
PrevalenceAnalyzer_HIV Implemented Prevalence stratified by HIV status, age, sex analyzer_prevalence.py
PrevalenceAnalyzer_SDoH Implemented Prevalence stratified by a binary SDoH flag analyzer_prevalence.py
CauseDeathRateAnalyzer Implemented Cause-specific death rates analyzer_prevalence.py
OnARTByConditionAnalyzer Implemented ART coverage among people with a given condition analyzer_prevalence.py
OnARTByConditionAndSexAnalyzer Implemented Same, split by sex analyzer_prevalence.py
InterventionAnalyzer Implemented Per-agent intervention receipt over time analyzer_intervention.py
AdherenceAnalyzer Implemented Intervention uptake by condition status analyzer_intervention.py
MicrocostingAnalyzer Implemented Costs, YLD, YLL, DALYs (post-sim finalize) analyzer_cost.py
HRHAnalyzer Stub Human resource utilization (placeholder) analyzer_cost.py
HospitalizationAnalyzer Stub Hospitalizations (placeholder) analyzer_serviceuse.py
OutpatientVisitAnalyzer Stub Outpatient visits (placeholder) analyzer_serviceuse.py
PreventiveServiceAnalyzer Stub Preventive services (placeholder) analyzer_serviceuse.py
ERVisitAnalyzer Stub ER visits (placeholder) analyzer_serviceuse.py

Status key: Implemented = usable logic present. Stub = class exists but step()/apply() is empty or minimal.

Demography and Mortality Analyzers

DeathsByAgeSexAnalyzer

Counts new deaths each timestep by age and sex. Used with mighti/analysis/life_expectancy.py to build life tables.

deaths_an = mi.analyzers.DeathsByAgeSexAnalyzer(max_age=100)

Exports to_df() with columns age, sex, deaths.

AgeSexMxAnalyzer

Preferred source for period mortality rates m(x) in long simulations with births and turnover. Pools exposure at step start and deaths after people.step_die().

mx_an = mi.analyzers.AgeSexMxAnalyzer(max_age=100)
# After sim.run():
df_mx = mx_an.to_mx_df(year=2022)

Used by mi.life_expectancy.calculate_life_expectancy_from_age_sex_mx_analyzer().

SurvivorshipAnalyzer

Computes l(x) — fraction of the initial sex-specific cohort surviving to each age at simulation end. Best for closed-cohort studies; less ideal when births add agents mid-simulation.

surv_an = mi.analyzers.SurvivorshipAnalyzer(max_age=100)

ConditionAtDeathAnalyzer / CauseOfDeathYLLAnalyzer

Record deaths with condition flags and years of life lost. CauseOfDeathYLLAnalyzer reads cause labels from sim._mighti_death_cause when using CompetingRisksDeaths or AdditiveHazardDeaths.

cod_an = mi.analyzers.ConditionAtDeathAnalyzer(
    conditions=["Type2Diabetes", "MajorDepressiveDisorder"],
    ex_life_expectancy=80.0,  # or a reference e(x) DataFrame / callable
)

Prevalence Analyzers

PrevalenceAnalyzer_HIV

Primary analyzer used in mighti_main.py. Tracks prevalence by HIV status, age bin, and sex for all listed diseases.

prev_an = mi.analyzers.PrevalenceAnalyzer_HIV(
    prevalence_data=prevalence_data,
    diseases=["HIV", "Type2Diabetes"],
)

Pair with mighti.analysis.plotting helpers such as plot_mean_prevalence and plot_hiv_prevalence_vs_observed.

PrevalenceAnalyzer_SDoH

Stratifies prevalence by a binary SDoH attribute (default: neighbourhood_situation).

sdoh_prev = mi.analyzers.PrevalenceAnalyzer_SDoH(
    diseases=["Type2Diabetes"],
    sdoh_attr="neighbourhood_situation",
)

Intervention and Adherence Analyzers

InterventionAnalyzer

Logs per-agent receipt of named interventions each timestep (e.g., ART, housing).

intv_an = mi.analyzers.InterventionAnalyzer(
    interventions=["art", "housing"],
)

AdherenceAnalyzer

Compares intervention uptake (e.g., hiv.on_art) among agents with vs without a CASM condition.

adh_an = mi.analyzers.AdherenceAnalyzer(
    condition_key="majordepressivedisorder.affected",
    intervention_key="hiv.on_art",
)

Cost and Service-Use Analyzers

MicrocostingAnalyzer

Post-processes costs and disability outcomes at finalize(). Integrates with InterventionAnalyzer and condition duration/disability weights. See Microcosting and CEA for details.

cost_an = mi.analyzers.MicrocostingAnalyzer(
    unit_costs={...},
    disability_weights={...},
    discount_rate_costs=0.03,
    discount_rate_outcomes=0.03,
)

Use mi.analyzers.summarize_microcosting_results(cost_an) for aggregated totals.

Service-use stubs

HospitalizationAnalyzer, OutpatientVisitAnalyzer, PreventiveServiceAnalyzer, and ERVisitAnalyzer are registered in the public API but currently contain placeholder implementations (pass). Do not rely on them for production outputs until implemented.

Using Analyzers in a Simulation

Minimal example (matches mighti_main.py default):

import mighti as mi
import starsim as ss

prevalence_analyzer = mi.analyzers.PrevalenceAnalyzer_HIV(
    prevalence_data=prevalence_data,
    diseases=["HIV", "Type2Diabetes"],
)

sim = ss.Sim(
    ...
    analyzers=[prevalence_analyzer],
)
sim.run()

Demography / mortality stack example:

analyzers = [
    mi.analyzers.DeathsByAgeSexAnalyzer(max_age=100),
    mi.analyzers.AgeSexMxAnalyzer(max_age=100),
    mi.analyzers.SurvivorshipAnalyzer(max_age=100),
    mi.analyzers.ConditionAtDeathAnalyzer(
        conditions=["Type2Diabetes"],
    ),
    mi.analyzers.PrevalenceAnalyzer_HIV(
        prevalence_data=prevalence_data,
        diseases=diseases,
    ),
]

sim = ss.Sim(..., analyzers=analyzers)
sim.run()

# Post-process life expectancy (requires DeathsByAgeSexAnalyzer or AgeSexMxAnalyzer)
from mighti.analysis.life_expectancy import calculate_life_expectancy_from_age_sex_mx_analyzer

e0 = calculate_life_expectancy_from_age_sex_mx_analyzer(sim, year=2022)

Adding a New Analyzer

  1. Subclass starsim.Analyzer
  2. Define init_results() to register output structures (ss.Result or self.records)
  3. Override step() (and optionally start_step() / finalize()) to collect data
  4. Optionally implement to_df() for export
  5. Register the class in mighti/analyzers/__init__.py _EXPORTS

Related Files

  • mighti/analyzers/ — all analyzer modules
  • mighti/analysis/life_expectancy.py — life tables and e₀ from analyzer outputs
  • mighti/analysis/plotting.py — prevalence and LE plotting helpers
  • mighti_main.py — example with PrevalenceAnalyzer_HIV
  • tests/test_life_expectancy.py — analyzer + LE integration tests

Clone this wiki locally