openghg_inversions.postprocessing.inversion_output

Modern inversion output container and serialization helpers.

InversionOutput is the durable artifact produced by modern RHIME and by fixedbasis compatibility paths that have been routed through the modern postprocessing flow. It stores the sampled trace, canonical inversion inputs, retained BasisFunctions, and run/model/output metadata needed to reproduce postprocessing products.

The class deliberately stays product-neutral. Product modules such as make_outputs, make_paris_outputs, and legacy_outputs decide which output formats they support, how variables are named in those formats, and whether a product can handle multisector data. InversionOutput only exposes modern semantic access to the underlying inputs and trace, including variable role lookup for model-specific variable names. The current role mapping is a small bridge until the project decides whether to use CF metadata via cf_xarray or a custom accessor.

Serialization is DataTree-based: object-specific to_datatree methods own their durable representation, while the local helper functions expand xarray MultiIndexes around NetCDF/Zarr limitations. Those generic helpers should move to shared utilities once the serialization surface settles.

class openghg_inversions.postprocessing.inversion_output.InversionOutput(trace: InferenceData, inv_inputs: Dataset, basis_functions: FluxWeightedBasis, run_metadata: dict[str, ~typing.Any]=<factory>, model_metadata: dict[str, ~typing.Any]=<factory>, output_metadata: dict[str, ~typing.Any]=<factory>, provenance: dict[str, ~typing.Any]=<factory>)

Bases: object

Modern RHIME inversion output contract.

This object carries the runtime artifacts needed to reproduce and extend RHIME outputs without exposing fixedbasis fp_data or legacy inferpymc_postprocessouts dictionaries.

basis_functions: FluxWeightedBasis

property domain: str | None

Domain name from model metadata.

property end_date: str | None

Inversion end date from run metadata.

property end_time: Timestamp

End time for the inversion period.

property flux: DataArray

Prior flux carried by the retained basis functions.

classmethod from_datatree(dt: DataTree) → Self

Construct a modern InversionOutput from a serialised DataTree.

input_dataset(required_roles: Iterable[str] | str | None = None, *, optional_roles: Iterable[str] | str = ()) → Dataset

Return canonical inversion-input variables selected by semantic role.

inv_inputs: Dataset

property is_multisector: bool

Whether this output represents a multisector RHIME run.

classmethod load(file_path: str | Path) → Self

Load a modern InversionOutput artifact.

model_data(var_roles: Iterable[str] | str | None = None) → Dataset

Return model input data from the InferenceData constant groups.

model_metadata: dict[str, Any]

output_metadata: dict[str, Any]

property period_midpoint: Timestamp

Midpoint of the inversion period.

provenance: dict[str, Any]

run_metadata: dict[str, Any]

save(output_file: str | Path, output_format: Literal['netcdf', 'zarr'] | None = None) → None

Save modern InversionOutput to NetCDF or Zarr.

property site_names: DataArray

Site names from inversion inputs or run metadata.

property species: str | None

Species name from model metadata.

property start_date: str | None

Inversion start date from run metadata.

property start_time: Timestamp

Start time for the inversion period.

to_datatree() → DataTree

Convert the modern output to a serialisable DataTree.

trace: InferenceData

trace_dataset(var_roles: Iterable[str] | str | None = None) → Dataset

Return prior and posterior trace samples selected by semantic role.

variable_name(role: str) → str

Return the concrete variable name for a semantic role.

property variable_roles: dict[str, str]

Mapping from modern semantic roles to concrete model variable names.

openghg_inversions.postprocessing.inversion_output.convert_idata_to_dataset(idata: InferenceData, group_filters=['prior', 'posterior'], add_suffix=True) → Dataset

Merge all groups in an arviz InferenceData object into a single xr.Dataset.

Parameters:

• idata – arviz InferenceData containing traces (and other data)

• group_filters – Filters for the groups of the InferenceData. A group will be selected if a filter is a substring of the group name. So the groups “prior” and “prior_predictive” will both match the filter “prior”. The default filters select the “prior”, “prior_predictive”, “posterior”, and “posterior_predictive” groups.

• add_suffix – if True, rename the data variables so that they end in the name of the group they came from.

Returns:

xr.Dataset containing all data variables in the selected groups of the InferenceData

openghg_inversions.postprocessing.inversion_output.filter_data_vars_by_prefix(ds: Dataset, var_name_prefixes: str | list[str], sep: str = '_') → Dataset

Select data variables that match the specified filters.

For instance, if var_name_prefixes = ‘prior’, then any data variable whose name begins with ‘prior_’ will be selected. The underscore ‘_’ is added by default, but can be changed by specifying sep.

Parameters:

• ds – Dataset to filter.

• var_name_prefixes – (List of) prefix(s) to filter data variables by.

• sep – Separator for prefix; default is “_”.

Returns:

Dataset restricted to data variables whose names match the filter.

Return type:

xr.Dataset