openghg_inversions.basis.basis_functions#

BasisFunctions object to encapsulate representation of basis.

Example usage:

>> def apply_basis_functions(ds: xr.Dataset, bf: BasisFunctions) -> xr.Dataset: >> if “fp_x_flux” not in ds: >> return ds >> return bf.sensitivity(ds.fp_x_flux).rename(“H”).to_dataset()

openghg_inversions.basis.basis_functions.BasisFunctions#

alias of FluxWeightedBasis

class openghg_inversions.basis.basis_functions.FluxWeightedBasis(operator: BasisOperator, flux: DataArray)#

Bases: object

A thin wrapper pairing a BasisOperator with a flux field.

This class is intentionally lightweight: it stores the operator and the flux, and provides constructors that build the appropriate operator from a basis representation.

Notes

  • A flux with a source dimension can still be paired with a BucketBasisOperator; in that case the same basis is applied to each source when broadcasting occurs in downstream operations.

  • Alignment/broadcasting details are currently delegated to the operator implementations.

flux: DataArray#
classmethod from_basis_flat(basis_flat: DataArray, flux: DataArray, *, region_labels: Literal['range0', 'range1', 'basis_values'] = 'range0', operator_kwargs: Mapping[str, Any] | None = None) → FluxWeightedBasis#

Construct from a single-source (standard) flattened basis array.

Parameters:

  • basis_flat – Flattened basis labels on the inversion grid, e.g. dims like (lat, lon) (or whatever grid dims the operator expects). Values should label regions.

  • flux – Flux on the same grid dims as basis_flat. May optionally contain extra dims such as time or source; these will be carried along by downstream operations.

  • region_labels – Policy for the output state coordinate labels: - “range0”: 0..N-1 (legacy-friendly) - “range1”: 1..N - “basis_values”: use the unique positive labels found in basis_flat.

  • operator_kwargs – Optional kwargs forwarded to BucketBasisOperator.

Returns:

A FluxWeightedBasis pairing a BucketBasisOperator with the provided flux.

classmethod from_datatree(dt: DataTree) → FluxWeightedBasis#

Deserialise from a DataTree produced by to_datatree.

Parameters:

dt – DataTree with basis and flux groups.

Returns:

A FluxWeightedBasis instance.

Raises:

  • KeyError – If required groups are missing.

  • ValueError – If schema/version mismatch or flux variable missing.

classmethod from_multi_source_basis_flat(basis_flat: Mapping[str, DataArray], flux: DataArray | Mapping[str, DataArray], *, operator_kwargs: Mapping[str, Any] | None = None) → FluxWeightedBasis#

Construct from a multi-source flattened basis mapping.

Parameters:

  • basis_flat – Mapping from source name to that source’s flattened basis labels on the grid. Each value should be a DataArray on the inversion grid (e.g. dims like (lat, lon)).

  • flux – Flux on the inversion grid. Commonly has a source dimension coordinate matching the keys of basis_flat, but this is not required at construction time.

  • operator_kwargs – Optional kwargs forwarded to MultiSourceBucketBasisOperator.

Returns:

A FluxWeightedBasis pairing a MultiSourceBucketBasisOperator with the provided flux.

interpolate(state: DataArray, *, flux: bool = False) → DataArray#

Interpolate from state vector to the grid.

Parameters:

  • state – State vector values with dim matching the operator’s state dim (usually state).

  • flux – If True, apply flux-weighting using self.flux as weights. If False, returns the unweighted basis interpolation.

Returns:

Interpolated gridded array on the operator grid dims, with any non-dot dims preserved.

operator: BasisOperator#
plot(*, shuffle: bool = False, **plot_kwargs: Any) → Any#

Plot basis labels.

  • For single-source basis, returns the result of xarray’s plot call.

  • For multi-source basis, creates one subplot per source and returns (fig, axes).

Parameters:

  • shuffle – If True, randomly permute region labels for visual separation.

  • **plot_kwargs – Forwarded to xarray’s .plot().

Returns:

Plotting object(s). For multi-source, returns (fig, axes).

sensitivity(fp_x_flux: DataArray, fillna: bool = True) → DataArray#

Compute sensitivity (grid -> state) via the underlying operator.

This is typically used to form the reduced Jacobian:

H = operator.sensitivity(fp_x_flux)

Parameters:

  • fp_x_flux – Footprints multiplied by flux, on the inversion grid dims. May contain extra dims (e.g. time, site, source).

  • fillna – if True, fill NaNs in fp_x_flux with 0.0.

Returns:

Sensitivity with a state-like dimension as defined by the operator.

to_datatree() → DataTree#

Serialise to a DataTree with basis and flux groups.

Returns:

  • basis: BasisOperator DataTree (via operator.to_datatree()).

  • flux: a Dataset containing the flux DataArray as variable flux.

Return type:

A DataTree with

Raises:

KeyError – If serialisation would overwrite an existing group name.