plots

plots

Plotting utilities for visualizing TB simulation results.

The main entry point is :func:plot, which accepts a MultiSim, a single Sim, or a pre-built flat results dict. Use the select argument to filter metrics (by name, substring, or regex) and style to control appearance. See :func:plot for the full parameter list and examples.

Functions

Name	Description
plot	Plot simulation results (MultiSim, Sim, or flat results dict).
plot_household	Plot the structure of households and intra-household connections.

plot

plots.plot(
    results,
    select=None,
    title='',
    filename=None,
    n_cols=None,
    row_height=1.5,
    style=None,
    show=True,
)

Plot simulation results (MultiSim, Sim, or flat results dict).

Parameters

Name	Type	Description	Default
results		MultiSim, single Sim, or dict of flat results per scenario.	required
select		What to plot. None = all. List of exact names, or a dict with keys like (substring), regex, items, and/or exclude. Prefix a list entry with '~' to exclude it.	None
title	str	Figure suptitle.	''
filename	str / path	Output filename; if provided, save figure	None
n_cols	int	Number of subplot columns	None
row_height	float	Row height in inches. Default 1.5.	1.5
style	str	Any ss.style()-compatible style name (e.g. 'starsim', 'seaborn-v0_8-whitegrid').	None
show	bool	Call plt.show() when done.	True

Returns

Name	Type	Description
		matplotlib.figure.Figure

Examples::

tbsim.plot(msim)                                           # all metrics
tbsim.plot(msim, select=['n_infectious', 'prevalence'])    # exact names
tbsim.plot(msim, select=dict(like='prevalence'))           # substring match
tbsim.plot(msim, select=dict(regex=r'^n_'))                # regex match
tbsim.plot(msim, select=['~15+', '~None'])                 # exclude patterns
tbsim.plot(msim, style='starsim', n_cols=3)                # appearance
tbsim.plot(msim, filename='abc.png')                       # save to disk
tbsim.get_tb(sim).plot()                                   # via disease object

plot_household

plots.plot_household(
    households_or_network,
    title='Household Network Structure',
    figsize=(12, 8),
    max_households=30,
    edge_mode='auto',
    layout='ring',
    layout_seed=123,
    show_labels=False,
    show=True,
    filename=None,
)

Plot the structure of households and intra-household connections.

This function creates a network visualization where: - Nodes represent individual agents - Edges represent household connections (actual network edges by default) - Different colors represent different households - Node size is proportional to household size

Parameters

Name	Type	Description	Default
households_or_network		one of: - list of households (each household is a list/array of UIDs) - an ss.Sim with a network exposing household_ids - a household network exposing household_ids	required
title	str	Title for the plot	'Household Network Structure'
figsize	tuple	Figure size (width, height)	(12, 8)
max_households	int / None	maximum households to render (largest first). Use None to render all (can be very dense for large sims).	30
edge_mode	str	one of 'auto', 'actual', 'complete'. - 'actual': draw true edges from the network object - 'complete': reconstruct full within-household cliques - 'auto' (default): use 'actual' for sim/network input and 'complete' for explicit household-list input	'auto'
layout	str	one of 'ring', 'grid', 'spring', 'kamada'. - 'ring': household-clustered circular layout (legacy style) - 'grid': household clusters arranged in rows/columns - 'spring': force-directed layout (less donut-like) - 'kamada': Kamada-Kawai layout (compact force-directed)	'ring'
layout_seed	int	random seed used for layout='spring'.	123
show_labels	bool	whether to draw UID labels inside nodes. Defaults to False for cleaner household figures.	False
show	bool	call plt.show().	True
filename	str / path / None	optional path to save figure.	None

Returns

Name	Type	Description
		networkx.Graph: The NetworkX graph object for further analysis