analyzers

analyzers

TBsim custom analyzers

Classes

Name	Description
DwellTime	Unified dwell-time analysis, aggregation, and visualization.
HouseholdStats	Track household size, age, and contact-mixing statistics over time.

DwellTime

analyzers.DwellTime(
    data=None,
    file_path=None,
    directory=None,
    prefix='',
    scenario_name='',
    debug=False,
)

Unified dwell-time analysis, aggregation, and visualization.

Constructor mode is auto-detected from the arguments supplied:

Plotter mode – pass data (DataFrame) or file_path (CSV path).
Aggregate mode – pass directory (and optional prefix).
Analyzer mode – pass none of the above; the instance will be attached to a Starsim simulation and record dwell times at each step.

Parameters

Name	Type	Description	Default
data	pd.DataFrame	Pre-loaded dwell-time DataFrame.	`None`
file_path	str	Path to a single CSV file with dwell-time data.	`None`
directory	str	Directory containing CSV result files for aggregation.	`None`
prefix	str	File prefix filter used with directory.	`''`
scenario_name	str	Label for the simulation scenario.	`''`
debug	bool	Enable verbose output.	`False`

Visualization types (via plot(kind=...)):

'histogram' – Histograms with KDE per state
'kaplan_meier' – Kaplan-Meier survival curves
'network' – Directed graph of state transitions
'validation' – Observed dwell-time histograms for validation

Example:

Aggregating multiple runs::

    dt = DwellTime(directory='results', prefix='Baseline')
    dt.plot('network')

During simulation::

    sim = ss.Sim(diseases=[TB()], analyzers=DwellTime(scenario_name="Baseline"))
    sim.run()
    sim.analyzers[0].plot('validation')

Methods

Name	Description
finalize	Finalize the analysis: map state names and save to file.
plot	Create a visualization of the dwell-time data.
save	Save dwell time data to CSV and metadata files.
step	Execute one time step of dwell time analysis.
validate_dwell_time_distributions	Validate dwell time distributions using KS tests.

finalize

analyzers.DwellTime.finalize()

Finalize the analysis: map state names and save to file.

plot

analyzers.DwellTime.plot(kind='histogram', **kwargs)

Create a visualization of the dwell-time data.

Parameters

Name	Type	Description	Default
kind	str	One of `'histogram'`, `'kaplan_meier'`, `'network'`, `'validation'`.	`'histogram'`
**kwargs		Forwarded to the underlying plot method.	`{}`

Raises

Name	Type	Description
	ValueError	If kind is not recognised.

save

analyzers.DwellTime.save(filename='dwelltime.csv')

Save dwell time data to CSV and metadata files.

step

analyzers.DwellTime.step()

Execute one time step of dwell time analysis.

validate_dwell_time_distributions

analyzers.DwellTime.validate_dwell_time_distributions(expected_distributions)

Validate dwell time distributions using KS tests.

HouseholdStats

analyzers.HouseholdStats(
    network_name='householdnet',
    age_bins=(0, 5, 15, 50, 100),
    save_at=None,
    **kwargs,
)

Track household size, age, and contact-mixing statistics over time.

Works with any network that exposes a household_ids state (e.g. starsim.HouseholdNet). At each timestep the analyzer counts alive agents per household and records summary statistics.

Parameters

Name	Type	Description	Default
network_name	str	Name of the household network on `sim.networks` (default `'householdnet'`).	`'householdnet'`
age_bins	tuple	Bin edges for the age distribution histogram (default `(0, 5, 15, 50, 100)`).	`(0, 5, 15, 50, 100)`

Results (per timestep): mean_hh_size, median_hh_size, max_hh_size, n_households, mean_hh_age, median_hh_age, mean_age, and one count per age bin.

Plots

plot_stats() – four-panel figure: household size over time, number of households, average household age over time, and initial vs. final household size distribution. plot_matrix() – three-panel figure: age distribution over time, age-mixing matrix at simulation start, age-mixing matrix at end. plot_normalized_matrix() – four-panel figure: contacts per person (C_ij / n_j) and proportionate mixing ratio (C_ij / E_ij) at simulation start and end. plot() – calls all three of the above.

Example::

import starsim as ss
import starsim_examples as sse
import tbsim

dhs_data = ...  # pandas DataFrame with hh_id and ages columns
net = ss.HouseholdNet(dhs_data=dhs_data)
analyzer = tbsim.HouseholdStats(network_name='householdnet')
sim = ss.Sim(
    diseases='sis', networks=net,
    demographics=[ss.Pregnancy(fertility_rate=20), ss.Deaths(death_rate=10)],
    analyzers=analyzer,
)
sim.run()
analyzer.plot()

Methods

Name	Description
from_multisim	Return an averaged HouseholdStats by combining results across replicates.
plot	Plot all household statistics (calls plot_stats, plot_matrix, and plot_normalized_matrix).
plot_from_multisim	Plot averaged household statistics across all replicates in a MultiSim.
plot_matrix	Three-panel figure: age distribution over time, initial and final age-mixing matrices.
plot_normalized_matrix	Four-panel figure: contacts-per-person and proportionate-mixing ratio at start and end.
plot_stats	Four-panel figure: household size, n_households, average household age, size distribution.

from_multisim

analyzers.HouseholdStats.from_multisim(msim, name=None)

Return an averaged HouseholdStats by combining results across replicates.

Averages time-series results and age-mixing matrices in-place on the first rep, and pools household-size histograms across all reps. Safe to call because MultiSim creates a separate copy of the sim (and its analyzers) for each replicate.

Args:

Returns

Name	Type	Description
		An object with the same structure as HousehouldStats, but with averaged/pooled values.

plot

analyzers.HouseholdStats.plot(stop=None, **kwargs)

Plot all household statistics (calls plot_stats, plot_matrix, and plot_normalized_matrix).

Parameters

Name	Type	Description	Default
stop		Right x-axis limit for time-series panels (e.g. 2025 or ss.date(‘2025-12-31’)).	`None`

plot_from_multisim

analyzers.HouseholdStats.plot_from_multisim(
    msim,
    name=None,
    stop=None,
    **kwargs,
)

Plot averaged household statistics across all replicates in a MultiSim.

Parameters

Name	Type	Description	Default
msim		A starsim MultiSim whose sims each contain a HouseholdStats analyzer.	required
name	str	The analyzer’s registered name (default ‘householdstats’).	`None`
stop		Right x-axis limit for time-series panels (e.g. 2025).	`None`

plot_matrix

analyzers.HouseholdStats.plot_matrix(stop=None, **kwargs)

Three-panel figure: age distribution over time, initial and final age-mixing matrices.

Parameters

Name	Type	Description	Default
stop		Right x-axis limit for the stacked area panel. If a snapshot was saved at this year (via save_at), the “final” matrix panel shows that snapshot instead of the true simulation end.	`None`

plot_normalized_matrix

analyzers.HouseholdStats.plot_normalized_matrix(stop=None, **kwargs)

Four-panel figure: contacts-per-person and proportionate-mixing ratio at start and end.

Top row: contacts per person in the x-axis age group (C_ij / n_j). Bottom row: departure from proportionate mixing (C_ij / E_ij), where E_ij = C_total * p_i * p_j and p_k = n_k / N. Left column: simulation start; right column: simulation end.

Parameters

Name	Type	Description	Default
stop		If provided and a snapshot was saved at this year (via save_at), the right column shows that snapshot instead of the true simulation end.	`None`

plot_stats

analyzers.HouseholdStats.plot_stats(stop=None, **kwargs)

Four-panel figure: household size, n_households, average household age, size distribution.

Parameters

Name	Type	Description	Default
stop		Right x-axis limit for time-series panels (e.g. 2025 or ss.date(‘2025-12-31’)).	`None`