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_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.	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_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.