openghg_inversions.correlated_state#
Labelled arithmetic-moment contracts for correlated positive states.
This backend-neutral module validates an already-reduced state coordinate and
an explicitly dense arithmetic covariance, then derives the latent Gaussian
moments required to represent those moments with a multivariate LogNormal
distribution. PyMC graph construction lives in
openghg_inversions.models.components.
The covariance accepted here is for the reduced inversion state, not a native grid. The implementation materializes dense covariance, latent-covariance, and Cholesky arrays, with quadratic memory use and cubic factorization cost. Native covariances with tens or hundreds of thousands of grid cells must therefore remain structured and be projected into the reduced state before constructing this contract.
This module does not perform that native-to-reduced transformation or remove
state components. The coherent covariance, transformed-forward-model, and
aggregation-error identities are exact only for a jointly Gaussian state.
Reusing the resulting first two moments while representing the retained state
as LogNormal and the unresolved contribution as Gaussian is a moment-matched
closure, not exact marginalization of a LogNormal state. Fixing a state at a
known value is instead handled by models.StateActivity.
The main entry point is CorrelatedLognormalPrior. Its constructor eagerly
computes xarray inputs and owns independent copies; to_dataset and
from_dataset provide persistence boundaries. Construction warns before
dense covariance materialization when the reduced state exceeds 1,000
components.
- class openghg_inversions.correlated_state.CorrelatedLognormalPrior(mean: DataArray, arithmetic_covariance: DataArray | ndarray, *, covariance_dim: str | None = None)#
Bases:
objectValidated labelled moments for one correlated positive state vector.
The arithmetic covariance is an already-reduced dense matrix. It uses a distinct second dimension whose entries follow the primary state coordinate in the same order. Only the primary axis owns the rich scientific coordinate, avoiding duplicate MultiIndex level coordinates while retaining an explicit labelled-row contract.
- Variables:
mean – Arithmetic mean with dimension
(state_dim,). Access returns an independent deep copy.arithmetic_covariance – Dense arithmetic covariance with dimensions
(state_dim, covariance_dim). Access returns an independent deep copy.latent_mean – Derived Gaussian mean with dimension
(state_dim,). Access returns an independent deep copy.latent_covariance – Derived Gaussian covariance with dimensions
(state_dim, covariance_dim). Access returns an independent deep copy.latent_cholesky – Lower Cholesky factor with dimensions
(state_dim, covariance_dim). Access returns an independent deep copy.state_dim (str) – Name of the scientific state dimension.
covariance_dim (str) – Name of the same-order covariance column dimension.
Notes
Construction owns all supplied values. Array properties return deep copies so callers cannot mutate the cached validated moments through the public API.
- property arithmetic_covariance: DataArray#
Return the validated arithmetic covariance.
- Returns:
An independent deep copy of the dense labelled covariance.
- classmethod from_dataset(dataset: Dataset) → CorrelatedLognormalPrior#
Reload and revalidate a serialized correlated-state contract.
- Parameters:
dataset – Dataset produced by
to_dataset().- Returns:
A newly validated prior derived from the stored arithmetic moments.
- Raises:
ValueError – If schema metadata, variables, dimensions, labels, or cached latent moments are missing or inconsistent.
- Warns:
UserWarning – If the stored reduced state contains more than 1000 components. This is an operational threshold, not a mathematical limit.
Notes
Stored latent values are checked against moments recomputed from the eagerly materialized arithmetic inputs; they are never trusted as an alternative construction path.
- property latent_cholesky: DataArray#
Return the Cholesky factor of the latent covariance.
- Returns:
An independent deep copy of the dense lower-triangular factor.
- property latent_covariance: DataArray#
Return the derived latent Gaussian covariance.
- Returns:
An independent deep copy of the dense latent covariance.
- property latent_mean: DataArray#
Return the derived latent Gaussian mean.
- Returns:
An independent deep copy of the labelled latent mean.