openghg_inversions.observation_error#

Backend-neutral aggregation-error covariance contracts.

Aggregation error is fixed input data, separate from measurement error and the inferred RHIME model-error term. Prepared inversion inputs may represent it exactly as a dense covariance, efficiently as a low-rank-plus-diagonal covariance, or diagnostically as independent standard deviations.

class openghg_inversions.observation_error.AggregationError(mode: Literal['none', 'dense', 'low_rank', 'diagonal'], marginal_variance: ndarray, covariance: DataArray | None = None, factor: DataArray | None = None, diagonal_variance: DataArray | None = None)#

Bases: object

Validated aggregation-error representation selected for a likelihood.

Model builders trust this value as already validated. Scientific runners should construct it through resolve_aggregation_error(), which selects and validates a coherent-reduction representation. Direct construction is an expert seam, primarily useful when testing model components, and the caller then owns the coherence of the mode, payload, marginal variance, coordinates, and numerical covariance properties.

Parameters:

  • mode – Concrete covariance representation.

  • marginal_variance – Observation-aligned covariance diagonal.

  • covariance – Optional dense covariance matrix.

  • factor – Optional low-rank covariance factor.

  • diagonal_variance – Optional independent residual variance for a low-rank representation.

covariance: DataArray | None = None#
diagonal_variance: DataArray | None = None#
factor: DataArray | None = None#
marginal_variance: ndarray#
mode: Literal['none', 'dense', 'low_rank', 'diagonal']#
openghg_inversions.observation_error.aggregation_error_input_names(data: Dataset, requested: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal']) → tuple[str, ...]#

Return labelled arrays required by the selected error component.

Parameters:

  • data – Prepared inputs containing available aggregation-error products.

  • requested – Requested representation, or "auto".

Returns:

Variable names required to materialize the selected representation.

Raises:

ValueError – If the requested mode is invalid or automatic selection is ambiguous.

openghg_inversions.observation_error.resolve_aggregation_error(data: Dataset, mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'] = 'auto', *, output_dim: str = 'nmeasure', covariance_dim: str = 'nmeasure_cov') → AggregationError#

Validate and select an aggregation-error covariance representation.

In "auto" mode, a structured representation takes precedence over aggregation_error_sd because that vector is commonly retained as a marginal diagnostic beside the exact covariance. Supplying both dense and low-rank forms is ambiguous and therefore requires an explicit selection.

Parameters:

  • data – Prepared inversion inputs containing the requested aggregation- error representation.

  • mode – Representation to use, or "auto" to select from available inputs.

  • output_dim – Observation dimension used by error vectors and the first covariance dimension.

  • covariance_dim – Second dimension required for a dense covariance.

Returns:

Validated aggregation-error arrays and their marginal variance.

Raises:

ValueError – If the selected inputs are absent, malformed, inconsistent, non-finite, or not a valid covariance representation.

openghg_inversions.observation_error.select_aggregation_error_mode(data: Dataset, requested: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal']) → Literal['none', 'dense', 'low_rank', 'diagonal']#

Select an aggregation-error representation without materializing it.

Parameters:

  • data – Prepared inversion inputs containing any available aggregation-error representations.

  • requested – Requested representation, or "auto" to infer one from the available inputs.

Returns:

The selected concrete aggregation-error representation.

Raises:

ValueError – If requested is invalid or "auto" finds both dense and low-rank representations.

openghg_inversions.observation_error.validate_complete_observation_covariance(aggregation_error: AggregationError, independent_variance: ndarray) → None#

Optionally check a custom complete observation covariance is positive definite (PD).

Built-in pipelines construct covariance components with known guarantees and do not call this eager diagnostic. Custom pipelines may use it after adding their fixed independent variance. For an LRPD covariance, the structural check uses F F.T + diag(d) directly: it is positive definite exactly when the rows of F corresponding to zero entries of non-negative d are linearly independent.

openghg_inversions.observation_error.validate_observation_error_arrays(observations: DataArray, observation_error: DataArray, minimum_error: DataArray | None, *, owner: str, output_dim: str = 'nmeasure') → None#

Validate the named scientific arrays consumed by an error component.

Parameters:

  • observations – Observed mole fractions.

  • observation_error – Reported observation-error standard deviations.

  • minimum_error – Optional minimum total-error standard deviations.

  • owner – Name of the likelihood/error component consuming the arrays.

  • output_dim – Required observation dimension.

Raises:

ValueError – If an input is not an aligned observation vector or an error array is non-numeric, non-finite, or negative.