openghg_inversions.inversion_data.xarray_adapter#

Adapt source-neutral xarray data to the canonical RHIME input contract.

The public prepare_rhime_inputs_from_xarray() adapter starts after data acquisition. It accepts site data already held in xarray objects, applies a retained BasisFunctions object when only footprint-times-flux caches are available, and returns the same RhimePreparedInputs contract used by the OpenGHG-backed preparation path.

Each site-local input dataset must contain a time dimension and the observation variables required by openghg_inversions.inversion_inputs.make_inv_inputs(): mf, mf_error, mf_repeatability, and mf_variability. They must also contain either canonical H or one of fp_x_flux and fp_x_flux_sectoral. When both cache variables are present, the explicitly sector-resolved fp_x_flux_sectoral is used. Optional H_bc retains the existing sampled boundary-condition contribution.

Site data must be supplied as an ordered site-to-Dataset mapping or a root DataTree with one direct child node per site, each holding a site-local Dataset and no nested children. Direct Dataset, dense Dataset(site, time), and pre-stacked nmeasure layouts are deliberately outside this adapter’s contract.

Canonical H uses dimensions (region, time) for single-source and source-specific gathered state, or (region, time, source) for a shared rectangular state. A gathered source-specific region coordinate is a unique MultiIndex over (source, region_in_source) and must exactly match the retained operator state. Multisector inputs additionally require source-resolved retained prior flux with exactly the same source names and order. The adapter rejects broadcasting one total prior flux across multiple sectors because that would corrupt flux reconstruction.

The adapter is pure: it never mutates the supplied xarray objects or retained basis functions. Known footprint-times-flux caches and non-time-dependent data variables are excluded from the returned canonical inputs; other observation-aligned extension variables are retained. The reserved fixed_baseline extension is rejected until a reusable semantic Baseline component defines its likelihood and output behavior.

Every supplied row is active. Each site therefore needs an explicit, nonempty, unique datetime64 time coordinate without NaT. Observation, projected sensitivity, and optional H_bc values must be finite. Required observation and error fields, selected H or cache, and optional H_bc must declare the same exact nonempty unit string; the adapter performs no conversion. Labels on explicit source dimensions must be nonempty, unique Python or NumPy strings in their intended order, and non-string labels are not coerced. Repeated source values inside a gathered (source, region_in_source) state MultiIndex are valid.

Use RhimePreparedInputs.save and load() for durable canonical artifacts. Serialized or otherwise pre-stacked nmeasure data should not be passed back through this adapter.

Create canonical RHIME inputs from source-neutral xarray site data.

Input must be an ordered mapping or a DataTree with one direct child Dataset per site. Mapping keys and DataTree child names define site order unless sites explicitly selects and orders them. Direct Dataset, dense Dataset(site, time), and pre-stacked nmeasure layouts are rejected.

Each site dataset must follow the module-level variable contract. Cached fp_x_flux or fp_x_flux_sectoral is projected through basis_functions.sensitivity before site-time observations are gathered to nmeasure. Existing H is accepted directly. The retained operator and prior flux are preserved; artifact provenance may be added to a new BasisFunctions value in the returned prepared inputs.

Every row is active. Per-site time coordinates must be explicit, nonempty, unique datetime64 values without NaT; valid non-monotonic order is preserved. Observation variables must have exactly dimension ("time",). Required observations, projected H, and optional H_bc must be finite. Required observation and error fields, selected H or cache, and optional H_bc must have the same exact nonempty unit string as mf across all sites; no conversion is performed. Release-coordinate pairs are all-or-none across retained sites. Labels on an explicit source dimension are nonempty, unique Python or NumPy strings and are never coerced from bytes or numbers. Repeated source values in a gathered source-specific state MultiIndex remain valid.

Persist and reopen canonical artifacts with RhimePreparedInputs.save and load(); do not pass serialized nmeasure data back to this adapter. The reserved fixed_baseline input is rejected until a reusable semantic Baseline component is available; use sampled H_bc or omit it.

Parameters:

data – Site data as a DataTree or site-to-Dataset mapping.
basis_functions – Self-contained retained basis object, including the prior/reference flux used for posterior reconstruction. Multisector data require matching ordered source coordinates on retained flux and any source-specific operator.
sites – Optional site selection and order.
averaging_period – One common period, a site-aligned sequence or mapping, or None.
bc_freq – Frequency used to expand sampled H_bc contributions.
min_error – Minimum model error accepted by make_inv_inputs.
min_error_per_site – Whether calculated minimum errors vary by site. Defaults to False, matching the OpenGHG-backed RHIME preparation route.
start_date – Optional frequency anchor passed to make_inv_inputs.

Returns:

Canonical prepared inputs accepted by openghg_inversions.rhime.run_rhime_from_prepared_inputs().

Raises:

TypeError – If the input container or mapping values are unsupported, or basis_functions is not a BasisFunctions object.
ValueError – If site data violate the documented variable, dimension, source-order, or site-alignment contract, or contain the deferred fixed_baseline extension.