cell_data.DiagnosticQueries

cell_data.DiagnosticQueries(registry)

Pre-built queries for common diagnostic plots and analysis.

All methods return pandas DataFrames for easy integration with matplotlib, seaborn, and other scientific Python libraries.

Attributes

Name	Type	Description
registry		The RunRegistry to query.

Examples

>>> queries = DiagnosticQueries(registry)
>>> # Time series at a location
>>> df = queries.get_cell_timeseries(
...     longitude=-116.1,
...     latitude=33.9,
...     variable="treeCount",
... )

>>> # Spatial snapshot
>>> df = queries.get_spatial_snapshot(
...     step=50,
...     variable="treeCount",
...     run_hash="a1b2c3d4e5f6",
... )

Methods

Name	Description
get_all_variables_at_step	Get all variables for all cells at a specific timestep.
get_bbox_timeseries	Get aggregated time series for a bounding box region.
get_cell_timeseries	Get time series for a specific location.
get_parameter_comparison	Compare a variable across parameter values.
get_replicate_cv	Compute coefficient of variation for each replicate’s time series.
get_replicate_uncertainty	Get mean and confidence intervals across replicates.
get_spatial_snapshot	Get spatial data for a single timestep.

get_all_variables_at_step

cell_data.DiagnosticQueries.get_all_variables_at_step(
    step,
    run_hash,
    replicate=0,
)

Get all variables for all cells at a specific timestep.

Returns position columns plus all variable columns.

Parameters

Name	Type	Description	Default
step	int	The timestep to query.	required
run_hash	str	Run hash to filter by.	required
replicate	int	Replicate number (default: 0).	0

Returns

Name	Type	Description
	Any	DataFrame with position columns plus all variable columns.

get_bbox_timeseries

cell_data.DiagnosticQueries.get_bbox_timeseries(
    min_lon,
    max_lon,
    min_lat,
    max_lat,
    variable,
    run_hash=None,
    aggregation='AVG',
)

Get aggregated time series for a bounding box region.

Parameters

Name	Type	Description	Default
min_lon	float	Minimum longitude.	required
max_lon	float	Maximum longitude.	required
min_lat	float	Minimum latitude.	required
max_lat	float	Maximum latitude.	required
variable	str	Variable name to analyze (e.g., “treeCount”, “avg.height”).	required
run_hash	str | None	Optional run hash filter.	None
aggregation	str	Aggregation function (AVG, MIN, MAX, SUM).	'AVG'

Returns

Name	Type	Description
	Any	DataFrame with: step, replicate, run_hash, value, n_cells.

get_cell_timeseries

cell_data.DiagnosticQueries.get_cell_timeseries(
    longitude,
    latitude,
    variable,
    run_hash=None,
    tolerance=0.01,
    show_sql=False,
)

Get time series for a specific location.

Parameters

Name	Type	Description	Default
longitude	float	Longitude of the cell.	required
latitude	float	Latitude of the cell.	required
variable	str	Variable name to extract (e.g., “treeCount”, “avg.height”).	required
run_hash	str | None	Optional filter by run hash.	None
tolerance	float	Spatial tolerance in degrees (default: ~1km at equator).	0.01
show_sql	bool	If True, print the SQL query for copy/paste modification.	False

Returns

Name	Type	Description
	Any	DataFrame with columns: step, replicate, value, run_hash.

get_parameter_comparison

cell_data.DiagnosticQueries.get_parameter_comparison(
    variable,
    param_name,
    step=None,
    aggregation='AVG',
    show_sql=False,
)

Compare a variable across parameter values.

Parameters

Name	Type	Description	Default
variable	str	Variable name to analyze (e.g., “treeCount”, “avg.height”).	required
param_name	str	Parameter name to group by. Use "label" to group by run labels assigned via registry.label_run(). If param_name isn’t a declared sweep parameter (i.e. not in registry.list_config_columns()), falls back to run-level attributes set via registry.set_attributes(run_hash, <param_name>=...).	required
step	int | None	Optional timestep filter (if None, groups by step).	None
aggregation	str	Aggregation function (AVG, MIN, MAX, SUM).	'AVG'
show_sql	bool	If True, print the SQL query for copy/paste modification.	False

Returns

Name	Type	Description
	Any	DataFrame with columns: param_value, step, mean_value, std_value, n_cells.

get_replicate_cv

cell_data.DiagnosticQueries.get_replicate_cv(
    variable,
    run_hash,
    burn_in=0,
    extinction_threshold=0.01,
)

Compute coefficient of variation for each replicate’s time series.

For each replicate: 1. Get spatially-averaged values at each timestep (after burn_in) 2. Compute CV = std(values) / mean(values) 3. Return inf if mean < extinction_threshold (extinction)

This is the correct way to measure stability - computing CV per replicate then averaging, rather than computing CV on cross-replicate means which can hide instability when replicates oscillate out of phase.

Parameters

Name	Type	Description	Default
variable	str	Export variable to analyze (e.g., “totalCover”)	required
run_hash	str	Run hash to filter by	required
burn_in	int	Steps to skip before measuring (default: 0)	0
extinction_threshold	float	Mean below this is considered extinction (default: 0.01)	0.01

Returns

Name	Type	Description
	dict[str, Any]	Dict with keys:
	dict[str, Any]	- ‘mean_cv’: Average CV across replicates (inf if any extinct)
	dict[str, Any]	- ‘replicate_cvs’: List of per-replicate CVs (inf for extinct)
	dict[str, Any]	- ‘n_replicates’: Number of replicates
	dict[str, Any]	- ‘n_timesteps’: Timesteps per replicate after burn-in
	dict[str, Any]	- ‘extinct_replicates’: List of replicate indices with extinction

get_replicate_uncertainty

cell_data.DiagnosticQueries.get_replicate_uncertainty(
    variable,
    run_hash,
    step=None,
    confidence=0.95,
)

Get mean and confidence intervals across replicates.

Parameters

Name	Type	Description	Default
variable	str	Variable name to analyze (e.g., “treeCount”, “avg.height”).	required
run_hash	str	Run hash to filter by.	required
step	int | None	Optional timestep filter (if None, aggregates across all steps).	None
confidence	float	Confidence level for intervals (default 0.95 for 95% CI).	0.95

Returns

Name	Type	Description
	Any	DataFrame with: step, mean, std, ci_low, ci_high, n_replicates.

get_spatial_snapshot

cell_data.DiagnosticQueries.get_spatial_snapshot(
    step,
    variable,
    run_hash,
    replicate=0,
)

Get spatial data for a single timestep.

Useful for creating heatmaps or choropleth maps.

Parameters

Name	Type	Description	Default
step	int	The timestep to query.	required
variable	str	Variable name to extract (e.g., “treeCount”, “avg.height”).	required
run_hash	str	Run hash to filter by.	required
replicate	int	Replicate number (default: 0).	0

Returns

Name	Type	Description
	Any	DataFrame with columns: longitude, latitude, value.