openghg_inversions.rhime.preparation

Named scientific preparation stages for RHIME recipes.

The functions in this module form the backend-neutral preparation spine used by openghg_inversions.rhime.run_rhime() and copied project runners:

retrieve/reload -> filter -> basis -> sensitivities -> labelled assembly.

Merged data and xarray objects supplied to these stages are borrowed. Stages return new handoffs when they need to attach variables or metadata and never mutate caller-owned datasets. Retrieval may read OpenGHG stores or a merged data cache and may write a requested merged-data artifact. Filtering may compute when a selected filter cannot operate lazily. Basis construction may read, fit, or write a basis artifact, and sensitivity construction may execute the basis and boundary-condition algorithms. Labelled assembly validates the durable RhimePreparedInputs artifact but does not make its arrays eager. Backend-specific materialization is kept in openghg_inversions.rhime.materialization so this module reads as the scientific transformation from merged observations to labelled inputs.

openghg_inversions.rhime.preparation.assemble_rhime_inputs(merged: RhimeMergedData, basis_functions: FluxWeightedBasis, site_data: Mapping[str, Dataset], data_args: Mapping[str, Any]) → RhimePreparedInputs

Construct and validate durable, backend-neutral RHIME model inputs.

The stage attaches domain metadata to shallow per-site copies, assembles observation-aligned arrays, applies the satellite boundary-condition scaling, and retains basis and site metadata. It also preserves the legacy construction of the minimum-error floor and boundary-condition temporal parameterization. Those are inverse-model settings, not properties of the acquired data; moving them to their model components is a later semantic change. This stage does not cross the PyMC materialization boundary.

openghg_inversions.rhime.preparation.build_rhime_basis(merged: RhimeMergedData, data_args: Mapping[str, Any]) → FluxWeightedBasis

Load or fit the retained RHIME basis for filtered observations.

This stage may read or write basis artifacts and may execute the selected basis algorithm. It treats merged as borrowed and does not build sensitivities.

openghg_inversions.rhime.preparation.build_rhime_sensitivities(merged: RhimeMergedData, basis_functions: FluxWeightedBasis, data_args: Mapping[str, Any], *, multisector: bool) → dict[str, Dataset]

Construct labelled flux and optional boundary-condition sensitivities.

The stage creates per-site dataset copies, computes the basis projection, and may load boundary-condition basis data. merged and basis_functions remain borrowed.

openghg_inversions.rhime.preparation.filter_rhime_observations(merged: RhimeMergedData, data_args: Mapping[str, Any]) → RhimeMergedData

Filter borrowed observations and remove empty sites with aligned metadata.

The stage may compute site data if a filter cannot operate lazily. It returns a new merged-data handoff when filtering changes data and never constructs basis functions or model inputs.

openghg_inversions.rhime.preparation.retrieve_or_reload_rhime_data(data_args: Mapping[str, Any], *, multisector: bool, merged_data: RhimeMergedData | None = None) → RhimeMergedData

Retrieve, reload, or accept externally supplied merged RHIME data.

Passing merged_data is the explicit no-I/O path. The object remains borrowed and is returned unchanged after a sector-layout compatibility check. Otherwise this stage may read OpenGHG stores or a local merged artifact, optionally write merged data, sanitize flux arrays, print progress, and emit warnings. data_args is never mutated.

openghg_inversions.rhime.preparation.with_prepared_rhime_sites(run_spec: RhimeRunSpec, prepared: RhimePreparedInputs) → RhimeRunSpec

Align run provenance to the observations retained by preparation.