diagnostics.SimulationDiagnostics

diagnostics.SimulationDiagnostics(registry)

Diagnostic plotting backed by a RunRegistry.

Provides quick visualization methods for simulation sanity checks. All plot methods display inline by default and return the matplotlib Figure for further customization or saving.

Attributes

Name	Type	Description
registry		The RunRegistry containing simulation data.

Examples

>>> registry = RunRegistry("experiment.duckdb")
>>> diag = SimulationDiagnostics(registry)

>>> # Quick time series check
>>> diag.plot_timeseries("averageAge", run_hash="abc123")

>>> # Save to file
>>> fig = diag.plot_timeseries("averageAge", run_hash="abc123", show=False)
>>> fig.savefig("diagnostic.png")

Methods

Name	Description
plot_comparison	Compare variable across parameter values.
plot_spatial	Plot spatial scatter at a single timestep.
plot_timeseries	Plot variable over time.

plot_comparison

diagnostics.SimulationDiagnostics.plot_comparison(
    variable,
    group_by,
    aggregate='mean',
    step=None,
    session_id=None,
    title=None,
    show=True,
    show_sql=False,
    **params,
)

Compare variable across parameter values.

The group_by argument is auto-detected: it can be either a config parameter (from your sweep, e.g., ‘maxGrowth’) or an export variable (from simulation output, e.g., ‘FIRE_REGIME’).

Parameters

Name	Type	Description	Default
variable	str	Variable name to plot.	required
group_by	str	Variable to group by - can be either: - A config parameter (from your sweep, e.g., ‘maxGrowth’) - An export variable (from simulation, e.g., ‘FIRE_REGIME’)	required
aggregate	str	Spatial aggregation mode: “mean”, “sum”, “min”, “max”.	'mean'
step	int | None	If provided, creates bar chart at that step; else time series.	None
session_id	str | None	Filter to specific session.	None
title	str | None	Plot title.	None
show	bool	If True, display plot inline.	True
show_sql	bool	If True, print the SQL query for copy/paste modification.	False
**params	Any	Additional parameter filters.	{}

Returns

Name	Type	Description
	Any	matplotlib Figure.

Raises

Name	Type	Description
	ValueError	If variable or group_by not found, or no data.

Note

group_by works best with discrete values. Continuous values will create one group per unique value, which may be unwieldy. For continuous variables, consider binning in a custom SQL query.

plot_spatial

diagnostics.SimulationDiagnostics.plot_spatial(
    variable,
    step,
    run_hash,
    replicate=0,
    title=None,
    show=True,
)

Plot spatial scatter at a single timestep.

Creates a scatter plot colored by variable value. For real GIS work, users should export to geopandas.

Parameters

Name	Type	Description	Default
variable	str	Variable name to plot (e.g., “treeCount”, “avg.height”).	required
step	int	Timestep to visualize.	required
run_hash	str	Run hash to filter by.	required
replicate	int	Replicate number (default: 0).	0
title	str | None	Plot title.	None
show	bool	If True, display plot inline.	True

Returns

Name	Type	Description
	Any	matplotlib Figure.

Raises

Name	Type	Description
	ValueError	If variable not found or no data matches.

plot_timeseries

diagnostics.SimulationDiagnostics.plot_timeseries(
    variable,
    run_hash=None,
    session_id=None,
    aggregate='mean',
    show_replicates=True,
    step_range=None,
    title=None,
    show=True,
    **params,
)

Plot variable over time.

Parameters

Name	Type	Description	Default
variable	str	Variable name to plot (e.g., “averageAge”).	required
run_hash	str | None	Filter to specific run.	None
session_id	str | None	Filter to specific session.	None
aggregate	str	Spatial aggregation mode: “mean” (default), “sum”, “min”, “max”, or “none” (per-patch).	'mean'
show_replicates	bool	If True and aggregate != “none”, show uncertainty band across replicates.	True
step_range	tuple[int, int] | None	Optional (min_step, max_step) filter.	None
title	str | None	Plot title (auto-generated if None).	None
show	bool	If True, display plot inline.	True
**params	Any	Filter by parameter values (e.g., maxGrowth=10).	{}

Returns

Name	Type	Description
	Any	matplotlib Figure.

Raises

Name	Type	Description
	ValueError	If variable not found or no data matches filters.