openghg_inversions.rhime.co2#

Public CO2-family RHIME recipes.

class openghg_inversions.rhime.co2.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.build_co2_model(flux_sensitivity: DataArray, *, retained_prior: CorrelatedLognormalPrior, fixed_prior_contribution: DataArray, observations: DataArray, observation_error: DataArray, minimum_error: DataArray, aggregation_error: AggregationError, sigma_alignment: SigmaAlignment | None = None, sigma_prior: dict[str, Any] | None = None, fixed_model_mismatch: float | DataArray | None = None, state_activity: StateActivity | None = None, boundary_sensitivity: DataArray | None = None, bc_prior: dict[str, Any] | None = None, bc_state_activity: StateActivity | None = None, offset_prior: dict[str, Any] | None = None, offset_args: dict | None = None) → Model#

Build the CO2 coherent-reduction model from explicit scientific arrays.

flux_sensitivity is prepared once as the reduced operator H_alpha: exact-zero columns are omitted from the backend co2_sensitivity while flux_scaling retains the complete labelled scientific state. fixed_prior_contribution is then added with the shared coherent-affine component to produce modelled_concentration.

fixed_prior_contribution is the affine term H m - H_alpha (Pi m). The latter is a fixed prior contribution, not an atmospheric boundary condition. retained_prior contains the complete labelled arithmetic moments for the positive flux state.

Known fixed states remain in the public state and forward calculation but are omitted from the sampled correlated state. fixed_model_mismatch is an optional known concentration standard deviation. openghg_inversions leaves this policy unset by default; the Verification Games fixed likelihood passes 1 ppm explicitly. Inner and outer same-grid states remain in this one flux state and are distinguished by basis_group metadata retained for output-side selection. The model builds only their complete shared flux contribution. Optional boundary and offset terms remain scientifically distinct components named mu_bc and offset.

Direct custom callers are responsible for supplying scientifically coherent arrays from one preparation and for their positional semantics when labels are absent.

Parameters:

  • flux_sensitivity – Reduced CO2 sensitivity with observation dimension nmeasure and one labelled retained-state dimension.

  • retained_prior – Complete labelled arithmetic-moment prior for the retained positive state.

  • fixed_prior_contribution – Fixed coherent-reduction affine intercept named fixed_prior_contribution on nmeasure.

  • observations – Observed CO2 concentrations on nmeasure.

  • observation_error – Reported observation standard deviation.

  • minimum_error – Minimum independent model-data mismatch standard deviation.

  • aggregation_error – Prepared fixed aggregation-error representation.

  • sigma_alignment – Optional grouping policy for inferred additive model error.

  • sigma_prior – Optional prior arguments for inferred additive model error.

  • fixed_model_mismatch – Optional known scalar or labelled concentration standard deviation.

  • state_activity – Optional labelled activity policy for retained flux states.

  • boundary_sensitivity – Optional atmospheric boundary-condition sensitivity already resolved for the model, for example data.

  • bc_prior – Optional prior arguments for boundary-condition scaling.

  • bc_state_activity – Optional labelled activity policy for boundary states.

  • offset_prior – Optional prior for an offset component. When omitted, no offset is added. Site codes are derived from the site coordinate on observations.

  • offset_args – Extra keyword arguments for the offset component.

Returns:

A registered PyMC model containing the complete affine concentration and Gaussian likelihood.

Raises:

ValueError – If shared preparation, prior construction, or registered coordinate alignment fails, or if sigma_prior is supplied without sigma_alignment.

openghg_inversions.rhime.co2.build_co2_o2_model(*, observations: DataArray, fixed_prior_contribution: DataArray, co2_sensitivity: DataArray, o2_sensitivity: DataArray, aggregation_error: AggregationError, retained_prior: CorrelatedLognormalPrior, independent_error_sd: DataArray, state_activity: StateActivity | None = None, output_dim: str = 'observation') → Model#

Build the shared-state CO2/O2 affine model and fixed-error likelihood.

fixed_prior_contribution, both channel sensitivities, the retained prior, and every block of aggregation_error must be products of the same coherent reduction. CO2 and O2 retain separate sensitivity row axes because their numeric units are declared independently for every row. The Verification Games replay uses ppm for both channels; other scientific O2 products may, for example, use per meg. Sensitivity rows must already be expressed in their declared channel units per dimensionless flux scaling; covariance blocks use the corresponding row-by-column unit products, including the CO2/O2 cross-covariance.

The O2 sensitivity unconditionally embeds the fixed, signed O2-per-CO2 oxidation ratios declared by CO2/O2 preparation. The two channel sensitivities are therefore gathered and applied to the raw shared state once. A recipe starting from a ratio-free O2 sensitivity would need to apply its labelled species/state ratio factor before constructing that joint sensitivity.

The prepared-input runner validates the external independent_error_sd as finite and positive. Direct custom callers own that check, exact label alignment, row-unit consistency, coherent covariance provenance, and the embedded-ratio contract before calling this lower-level builder.

Parameters:

  • observations – Joint CO2-then-O2 observation vector on output_dim, with row-wise species and unit coordinates.

  • fixed_prior_contribution – Joint coherent affine intercept on the same observation axis and in the corresponding row units.

  • co2_sensitivity – CO2 sensitivity with its channel observation axis first and the retained-prior state axis second.

  • o2_sensitivity – O2 sensitivity with its distinct channel observation axis first and the same state axis; its shared-state columns already embed the fixed oxidation ratios.

  • aggregation_error – Joint fixed aggregation covariance, including its cross-channel block.

  • retained_prior – Correlated arithmetic-moment prior for the one state vector shared by both channels.

  • independent_error_sd – Joint per-row independent standard deviations in each observation row’s native units.

  • state_activity – Optional labelled policy fixing or activating retained states.

  • output_dim – Joint observation dimension used by the likelihood.

Returns:

A registered PyMC model containing the shared state, gathered joint linear signal, coherent affine intercept, and joint Gaussian likelihood.

Raises:

ValueError – If shared-state sensitivity preparation, activity resolution, or registered coordinate alignment fails.

openghg_inversions.rhime.co2.co2_model_input_names(prepared_inputs: RhimePreparedInputs, *, aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'], preserve_prepared_fixed_mismatch: bool) → tuple[str, ...]#

Declare prepared arrays consumed by the selected CO2 components.

Parameters:

  • prepared_inputs – Prepared RHIME artifact containing the candidate inversion inputs.

  • aggregation_error_mode – Aggregation-error representation selected for the likelihood.

  • preserve_prepared_fixed_mismatch – Include a prepared fixed mismatch field when present.

Returns:

Names of the arrays to materialize for model construction.

Raises:

ValueError – If a required prepared input is absent.

openghg_inversions.rhime.co2.evaluate_co2_o2_prior_forward_mean(*, fixed_prior_contribution: DataArray, co2_sensitivity: DataArray, o2_sensitivity: DataArray, retained_prior: CorrelatedLognormalPrior, state_activity: StateActivity | None = None, output_dim: str = 'observation') → DataArray#

Evaluate the reduced model so callers can verify prior-forward preservation.

Parameters:

  • fixed_prior_contribution – Joint coherent-reduction intercept on output_dim.

  • co2_sensitivity – CO2 retained-state sensitivity with its own observation dimension and the retained-prior state dimension.

  • o2_sensitivity – O2 retained-state sensitivity with a distinct observation dimension and the same retained-prior state dimension.

  • retained_prior – Correlated retained-state arithmetic moments.

  • state_activity – Optional labelled policy fixing or activating retained states. Structural zero columns are inactive in both channels.

  • output_dim – Dimension of the returned joint observation vector.

Returns:

The labelled joint prior-forward concentration fixed_prior_contribution + H_joint @ prior_state.

Raises:

ValueError – If the channel sensitivities cannot form one shared-state sensitivity or state_activity does not align with that state.

openghg_inversions.rhime.co2.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.

openghg_inversions.rhime.co2.run_rhime_co2(*, prepared_inputs: RhimePreparedInputs, sigma_alignment: SigmaAlignment | None = None, sigma_prior: dict[str, Any] | None = None, fixed_model_mismatch: float | DataArray | None = None, sampler: RhimeSampler | None = None, aggregation_error_mode: Literal['auto', 'none', 'dense', 'low_rank', 'diagonal'] = 'dense', no_model_error: bool = False) → InferenceData#

Materialize, build, and sample the CO2 coherent-reduction model.

This callable is the public production replay seam for an already validated RhimePreparedInputs artifact. It alone unpacks the prepared dataset and constructs the complete retained prior; the model builder receives named scientific values.

fixed_model_mismatch=None preserves a prepared fixed-mismatch field if present, otherwise omits the term. An explicit scalar or labelled vector overrides prepared data. By default, inferred model error varies by site over one shared time period. An explicit sigma_alignment overrides that alignment; no_model_error=True disables inferred model error. The Verification Games fixed-likelihood harness passes 1 ppm and disables inferred model error.

Parameters:

  • prepared_inputs – Validated coherent-reduction inputs for the CO2 recipe.

  • sigma_alignment – Optional grouping policy for inferred additive model error. The default is derived from the prepared site indicator.

  • sigma_prior – Optional prior arguments for inferred additive model error.

  • fixed_model_mismatch – Optional known scalar or labelled mismatch standard deviation. When omitted, a prepared value is preserved.

  • sampler – Optional RHIME sampler configuration.

  • aggregation_error_mode – Prepared aggregation-error representation to use in the likelihood.

  • no_model_error – If true, omit inferred additive model error.

Returns:

Sampled inference data annotated with the CO2 variable-role and model manifests.

Raises:

ValueError – If model-error options contradict no_model_error, or prepared inputs are missing, inconsistent, or fail model construction.

openghg_inversions.rhime.co2.run_rhime_co2_o2_from_prepared_inputs(*, prepared_inputs: Co2O2PreparedInputs, independent_error_sd: DataArray, state_activity: StateActivity | None = None, sampler: RhimeSampler | None = None) → InferenceData#

Build and sample the CO2/O2 model from prepared scientific inputs.

This advanced replay seam begins after channel preparation. The public run_rhime_co2_o2 name is reserved for the future complete production recipe, including acquisition, preparation, materialization, and outputs.

The fixed independent channel error is required and remains labelled. Run policy, such as the UOB prototype’s one ppm value for both channels, belongs to the caller rather than the model API.

Parameters:

  • prepared_inputs – Validated preparation handoff containing joint observations and affine intercept on ("observation",), separate channel sensitivities on their native observation axes and the retained state axis, a dense joint aggregation covariance, retained prior, ratio provenance, units, labels, and scientific provenance.

  • independent_error_sd – Positive finite fixed standard deviations on ("observation",). Labels and observation_units must match prepared_inputs.observations exactly. These values remain fixed data and are not an inferred mismatch amplitude.

  • state_activity – Optional labelled active/fixed policy on the retained state dimension. Omitted states use the model’s structural activity policy.

  • sampler – Optional RHIME sampler configuration. The accepted CO2/O2 NumPyro defaults are used when omitted.

Returns:

Restored inference data with observed concentrations in observed_data["y"], fixed independent standard deviations in constant_data["fixed_independent_error_sd"], labelled coordinates, data-dependent concentration units, scientific-role annotations, and JSON model metadata.

Raises:

ValueError – If the fixed independent standard deviation is not a finite positive real numeric vector or fails the model’s observation-label/unit contract. Label, state, covariance, and activity errors from model construction are also propagated.