openghg_inversions.basis.layout#

Grouped basis layout helpers.

This module contains the small internal representation used to combine partition-local basis labels into one flat basis map while preserving semantic state metadata. It is intentionally separate from basis-generation algorithms: algorithms decide how to split cells inside a mask or region class, while BasisLayout records how those partition-local outputs are assembled into the single state axis consumed by BucketBasisOperator.

BasisLayout does not infer a catch-all remainder region. Callers that need one should pass it as an explicit BasisPartition so the semantic group and local region label are visible in the resulting state metadata.

The current implementation is eager and in-memory. It is intended for small metadata/layout assembly steps after region masks and basis labels have already been loaded or generated. File loading, lazy execution, large-grid chunking, and public RHIME configuration are handled outside this module.

class openghg_inversions.basis.layout.BasisLayout(partitions: Sequence[BasisPartition], state_dim: str = 'state')#

Bases: object

Combine disjoint basis partitions into one flat label map.

This first implementation is intentionally eager and in-memory: partition label arrays are materialized as NumPy arrays while building the combined map. File loading, lazy execution, and large-grid chunking policy remain outside this small metadata/layout boundary.

Variables:
partitions: Sequence[BasisPartition]#
state_dim: str#
to_flat_basis(*, name: str = 'basis') → BasisLayoutResult#

Return a positive-label flat basis and metadata keyed by raw labels.

This method materializes partition labels and the combined map in memory.

Parameters:

name – Name to assign to the returned flat-basis DataArray.

Returns:

A combined basis map plus metadata indexed by basis_label. BucketBasisOperator maps that metadata onto the final state coordinate after its configured label policy is applied.

Raises:

  • ValueError – If partitions are empty, overlap, contain no mapped cells, or leave grid cells unmapped.

  • TypeError – If partition labels are not numeric.

class openghg_inversions.basis.layout.BasisLayoutResult(basis_flat: DataArray, state_metadata: Dataset)#

Bases: object

Combined flat basis labels plus raw-label keyed state metadata.

Variables:
basis_flat: DataArray#
state_metadata: Dataset#
class openghg_inversions.basis.layout.BasisPartition(name: str, labels: DataArray, group: str, attrs: Mapping[str, ~typing.Any]=<factory>)#

Bases: object

Partition-local basis labels and their semantic group name.

Positive integer values in labels are treated as local region labels. Non-positive values and NaNs are treated as cells outside this partition.

Variables:

  • name (str) – Stable partition name used in basis_partition metadata.

  • labels (xarray.core.dataarray.DataArray) – Partition-local label array. Positive integer values identify regions inside this partition.

  • group (str) – Semantic group name used in basis_group metadata.

  • attrs (collections.abc.Mapping[str, Any]) – Optional partition metadata reserved for future callers. These attrs are not currently serialized into the layout result.

attrs: Mapping[str, Any]#
group: str#
labels: DataArray#
name: str#
class openghg_inversions.basis.layout.BasisStateMetadata(dataset: Dataset)#

Bases: object

Semantic coordinates describing a basis operator state axis.

The metadata may start indexed by raw basis_label values from a flat basis layout or by the final operator state dimension. This value object owns validation and alignment so operator classes do not need to know the dataset schema beyond their state coordinate and raw basis-label order.

Variables:

dataset (xarray.core.dataset.Dataset) – Dataset containing basis_group, basis_partition, and region_in_partition variables indexed by either basis_label or a final state dimension.

assign_to_matrix(mat: DataArray, *, state_dim: str) → DataArray#

Attach metadata variables as coordinates on a basis matrix.

Parameters:

  • mat – Basis matrix whose state coordinate matches this metadata.

  • state_dim – State dimension used by mat and this metadata.

Returns:

mat with grouped metadata coordinates attached.

Raises:

ValueError – If this metadata is not already indexed by state_dim or required variables are malformed.

dataset: Dataset#
classmethod from_dataset(dataset: Dataset | BasisStateMetadata) → BasisStateMetadata#

Return dataset as a BasisStateMetadata instance.

Parameters:

dataset – Metadata dataset or an existing BasisStateMetadata.

Returns:

dataset wrapped as BasisStateMetadata.

classmethod from_matrix(mat: DataArray, *, state_dim: str) → BasisStateMetadata | None#

Extract complete basis state metadata from matrix coordinates.

Parameters:

  • mat – Basis matrix that may carry grouped metadata coordinates on the state dimension.

  • state_dim – Name of the state dimension on mat.

Returns:

Metadata indexed by state_dim if all grouped metadata coordinates are present, otherwise None.

on_state_dim(*, state_dim: str, state_coord: DataArray, basis_value_labels: Sequence[int] | ndarray) → BasisStateMetadata#

Return metadata indexed by the final operator state dimension.

Parameters:

  • state_dim – Final state dimension name.

  • state_coord – Final state coordinate after the operator label policy has been applied.

  • basis_value_labels – Raw basis labels ordered to match the operator state columns before final relabeling.

Returns:

Metadata aligned to state_coord and indexed by state_dim.

Raises:

ValueError – If metadata labels do not match basis labels, if raw labels are duplicated, if final-state metadata has the wrong length, or if required variables are missing.

to_dataset() → Dataset#

Return the metadata as an xarray dataset.