Skip to content

Matrix Views

A factory class responsible for creating virtual xarray Datasets from Consist's metadata.

This factory allows users to query the Consist metadata catalog for multi-dimensional data (matrices) and lazily load the corresponding Zarr stores from disk. It consolidates data across different runs into a single, unified xarray Dataset, indexed by run_id, year, and iteration, facilitating comparative analysis and exploration.

Attributes:

Name Type Description
tracker Tracker

An instance of the Consist Tracker, which provides access to the database engine and artifact resolution necessary for identifying and loading matrix data.

load_matrix_view(concept_key, variables=None, *, run_ids=None, parent_id=None, model=None, status=None)

Returns a lazy xarray Dataset containing all runs that match the concept_key.

This method queries the Consist database for all matrix-type artifacts associated with the given concept_key. It then lazily opens each corresponding Zarr store using xarray and concatenates them into a single xarray.Dataset along a new run_id dimension. This allows for convenient analysis of multi-dimensional data across different experimental runs.

Parameters:

Name Type Description Default
concept_key str

The semantic key (e.g., "model_output_grid", "simulation_results") identifying the collection of matrix artifacts to load.

 required
variables Optional[List[str]]

A list of variable names to load from each Zarr store. If None, all variables from each store will be loaded.

 None
run_ids Optional[List[str]]

Optional list of run IDs to include in the view.

 None
parent_id Optional[str]

Optional scenario/parent run ID to filter by.

 None
model Optional[str]

Optional model name to filter by.

 None
status Optional[str]

Optional run status to filter by (e.g., "completed").

 None

Returns:

Type Description
Dataset

A lazy-loaded xarray.Dataset containing the combined data from all matching matrix artifacts, with a new run_id dimension and year/iteration coordinates. Returns an empty xr.Dataset if no matching artifacts are found or can be loaded.

Raises:

Type Description
ImportError

If the xarray library is not installed.
RuntimeError

If the Tracker instance does not have a configured database connection.