openghg_inversions.rhime.co2.co2_o2_preparation#

Labelled scientific inputs for the CO2/O2 recipe.

CO2 and O2 keep distinct, potentially unequal observation axes at this public boundary. They are stacked only after their labels, state meanings, covariance blocks, and units have been checked.

class openghg_inversions.rhime.co2.co2_o2_preparation.Co2O2PreparedInputs(observations: DataArray, fixed_prior_contribution: DataArray, co2_sensitivity: DataArray, o2_sensitivity: DataArray, o2_co2_flux_ratio: DataArray | None, o2_co2_flux_ratio_unavailable_reason: str | None, aggregation_error: AggregationError, retained_prior: CorrelatedLognormalPrior, provenance: Mapping[str, ~typing.Any]=<factory>)#

Bases: object

Backend-neutral joint inputs with shared land and split-ocean states.

Callers should normally obtain this handoff from prepare_co2_o2_inputs() rather than constructing it directly.

Variables:

  • observations (xarray.core.dataarray.DataArray) – CO2 followed by O2 observations on ("observation",). Its gathered MultiIndex records species and the native channel labels, while observation_units records channel units. Aligned site and time coordinates are retained when supplied.

  • fixed_prior_contribution (xarray.core.dataarray.DataArray) – Joint affine intercept H m - H_alpha Pi m on the same labelled observation axis and in the channel-specific observation units.

  • co2_sensitivity (xarray.core.dataarray.DataArray) – Effective CO2 sensitivity on the native CO2 observation and retained-state dimensions, with row labels matching the native CO2 observations and state labels matching the retained prior. Units are CO2 observation units per dimensionless flux scale.

  • o2_sensitivity (xarray.core.dataarray.DataArray) – Effective O2 sensitivity on the native O2 observation and retained-state dimensions, with corresponding row and state labels. Shared-state columns already contain signed O2-per-CO2 ratios; the O2-ocean column is applied directly.

  • o2_co2_flux_ratio (xarray.core.dataarray.DataArray | None) – Optional signed, finite, negative O2-per-CO2 ratios on (retained_prior.state_dim,) for exactly the shared GPP, TER, and FF states. The indexed state labels and source coordinate match the retained prior, while attrs record direction, sign convention, and provenance. The borrowed payload may remain lazy.

  • o2_co2_flux_ratio_unavailable_reason (str | None) – Non-empty explanation when scalar state-resolved ratios cannot be exposed because the paired native O2 flux embeds spatial ratios before convolution. Exactly one of this value and o2_co2_flux_ratio is present.

  • aggregation_error (openghg_inversions.observation_error.AggregationError) – Validated dense joint aggregation error. Covariance rows use observation and columns use observation_cov in block order [[CO2, CO2/O2], [CO2/O2.T, O2]]; per-axis unit coordinates describe mixed-unit entries.

  • retained_prior (openghg_inversions.correlated_state.CorrelatedLognormalPrior) – Correlated prior over shared GPP/TER/FF and separate CO2- and O2-ocean retained states.

  • provenance (collections.abc.Mapping[str, Any]) – JSON-serializable preparation and data provenance.

aggregation_error: AggregationError#
co2_sensitivity: DataArray#
fixed_prior_contribution: DataArray#
o2_co2_flux_ratio: DataArray | None#
o2_co2_flux_ratio_unavailable_reason: str | None#
o2_sensitivity: DataArray#
observations: DataArray#
provenance: Mapping[str, Any]#
retained_prior: CorrelatedLognormalPrior#
openghg_inversions.rhime.co2.co2_o2_preparation.prepare_co2_o2_inputs(*, co2_observations: DataArray, o2_observations: DataArray, co2_prior_forward_mean: DataArray, o2_prior_forward_mean: DataArray, co2_sensitivity: DataArray, o2_sensitivity: DataArray, o2_co2_flux_ratio: DataArray | None, o2_co2_flux_ratio_unavailable_reason: str | None, co2_aggregation_covariance: DataArray, co2_o2_aggregation_covariance: DataArray, o2_aggregation_covariance: DataArray, retained_prior: CorrelatedLognormalPrior, co2_units: str, o2_units: str, provenance: Mapping[str, Any] | None = None) → Co2O2PreparedInputs#

Validate coherent-reduction channel products and form one joint likelihood.

The concrete recipe treats the O2 sensitivity as already containing fixed, signed O2-per-CO2 ratios for shared states. Supply their labelled values when they remain available, or an explicit reason why a native paired-flux construction cannot expose scalar ratios at this boundary.

Parameters:

  • co2_observations – One-dimensional CO2 observations with a unique indexed native observation coordinate.

  • o2_observations – One-dimensional O2 observations with a unique indexed coordinate whose dimension name differs from the CO2 dimension. Times and lengths may differ between channels.

  • co2_prior_forward_mean – Native CO2 prior mean H m on exactly the CO2 observation dimension and labels.

  • o2_prior_forward_mean – Native O2 prior mean H m on exactly the O2 observation dimension and labels.

  • co2_sensitivity – CO2 effective sensitivity with dimensions (CO2 observation, retained state) and exact observation and retained-prior indexes. Its O2-ocean column must be zero.

  • o2_sensitivity – O2 effective sensitivity with dimensions (O2 observation, retained state) and exact observation and retained-prior indexes. Its CO2-ocean column must be zero; signed O2-per-CO2 ratios are already embedded in shared-state columns.

  • o2_co2_flux_ratio – Optional labelled ratios for exactly the shared retained states. Values must be finite and negative, the source coordinate must match the prior, and attrs must declare direction "O2 flux per CO2 flux", the signed convention, and provenance.

  • o2_co2_flux_ratio_unavailable_reason – Explanation used only when labelled scalar ratios are unavailable. Exactly one of this argument and o2_co2_flux_ratio must be supplied.

  • co2_aggregation_covariance – CO2-by-CO2 dense covariance. Rows use the CO2 observation dimension; its distinct column dimension carries the same CO2 labels in the same order. Entries have squared CO2 observation units.

  • co2_o2_aggregation_covariance – CO2-row by O2-column cross-covariance, labelled by the native CO2 and O2 observation indexes. Entries have CO2 observation units times O2 observation units.

  • o2_aggregation_covariance – O2-by-O2 dense covariance. Rows use the O2 observation dimension; its distinct column dimension carries the same O2 labels in the same order. Entries have squared O2 observation units.

  • retained_prior – Retained correlated prior whose indexed state axis has source and tracer_scope coordinates for shared GPP/TER/FF, CO2 ocean, and O2 ocean states.

  • co2_units – Non-empty units label for CO2 observations and sensitivity rows.

  • o2_units – Non-empty units label for O2 observations and sensitivity rows.

  • provenance – Optional JSON-serializable preparation provenance.

Returns:

Labelled, backend-neutral joint inputs. Observation vectors, affine intercept, sensitivities, and available ratio provenance retain borrowed lazy payloads; dense covariance validation is the explicit eager aggregation-error boundary.

Raises:

ValueError – If units or provenance are invalid; observation, sensitivity, state, ratio, or covariance dimensions/indexes disagree; the ratio exactly-one, direction, sign, provenance, or numerical-value contract fails; cross-tracer ocean loadings are nonzero; or the assembled dense covariance is non-finite, asymmetric, or not positive semidefinite.