openghg_inversions.rhime#

Modern public RHIME run functions.

class openghg_inversions.rhime.RhimeModelSpec(species: str, domain: str, sectors: tuple[SectorSpec, ...], use_bc: bool = True, sigma_per_site: bool = True, add_offset: bool = False, pollution_events_from_obs: bool = False, no_model_error: bool = False, power: dict[str, Any] | float = 1.99)#

Bases: object

Model options used to build a RHIME PyMC model.

Parameters:

species – Primary species name.
domain – Model domain name.
sectors – Flux sectors included in the model.
use_bc – Whether boundary-condition scaling is included.
sigma_per_site – Whether model-error terms vary by site.
add_offset – Whether model-data offsets are included.
pollution_events_from_obs – Whether model error scales with observed enhancements instead of modelled enhancements.
no_model_error – Whether explicit model-error terms are disabled.
power – Exponent or prior specification used in likelihood error scaling.

add_offset: bool = False#

domain: str#

no_model_error: bool = False#

pollution_events_from_obs: bool = False#

power: dict[str, Any] | float = 1.99#

sectors: tuple[SectorSpec, ...]#

sigma_per_site: bool = True#

species: str#

use_bc: bool = True#

class openghg_inversions.rhime.RhimeOutputSpec(output_format: Literal['none', 'inv_out', 'basic', 'paris'] = 'inv_out', output_path: str | None = None, output_name: str = 'rhime', save_trace: str | Path | bool = False, save_inversion_output: str | Path | bool = True, country_file: str | None = None, paris_postprocessing_kwargs: dict[str, Any] | None = None)#

Bases: object

Output settings for a RHIME run.

Parameters:

output_format – Output mode. "inv_out" saves/returns the modern inversion output, "basic" and "paris" additionally create derived outputs, and "none" skips output products.
output_path – Directory for saved outputs.
output_name – Base output name.
save_trace – Trace save setting. If true, save to output_path using the default trace file name; if a path, save there.
save_inversion_output – Inversion-output save setting. Defaults to true for CLI-friendly behaviour.
country_file – Optional country mask file used by derived outputs.
paris_postprocessing_kwargs – Extra keyword arguments for PARIS output creation.

country_file: str | None = None#

output_format: Literal['none', 'inv_out', 'basic', 'paris'] = 'inv_out'#

output_name: str = 'rhime'#

output_path: str | None = None#

paris_postprocessing_kwargs: dict[str, Any] | None = None#

save_inversion_output: str | Path | bool = True#

save_trace: str | Path | bool = False#

class openghg_inversions.rhime.RhimeResult(run_spec: RhimeRunSpec, model_spec: RhimeModelSpec, output_spec: RhimeOutputSpec, inv_inputs: Dataset, idata: InferenceData, output_metadata: dict[str, ~typing.Any]=<factory>, outputs: dict[str, ~typing.Any]=<factory>, model: Model | None = None, inv_out: InversionOutput | None = None)#

Bases: object

Modern RHIME run result.

Parameters:

run_spec – Top-level run metadata.
model_spec – Model specification used to build the PyMC model.
output_spec – Output settings used by the run.
inv_inputs – Canonical xarray inversion inputs consumed by the model.
idata – ArviZ InferenceData returned by sampling.
output_metadata – Paths and notes for generated outputs.
outputs – In-memory derived outputs keyed by output kind.
model – Built PyMC model.
inv_out – Modern inversion output object when created.

idata: InferenceData#

inv_inputs: Dataset#

inv_out: InversionOutput | None = None#

model: Model | None = None#

model_spec: RhimeModelSpec#

output_metadata: dict[str, Any]#

output_spec: RhimeOutputSpec#

outputs: dict[str, Any]#

run_spec: RhimeRunSpec#

class openghg_inversions.rhime.RhimeRunSpec(start_date: str, end_date: str, sites: tuple[str, ...], averaging_period: tuple[str | None, ...], model: RhimeModelSpec, output: RhimeOutputSpec, split_by_sectors: bool = False)#

Bases: object

Top-level run metadata for a RHIME run.

Parameters:

start_date – Inclusive inversion start date.
end_date – Exclusive inversion end date.
sites – Sites included after data preparation and filtering.
averaging_period – Observation averaging period per retained site.
model – Mathematical model specification.
output – Output settings.
split_by_sectors – Whether flux data were prepared in sector-resolved mode.

averaging_period: tuple[str | None, ...]#

end_date: str#

model: RhimeModelSpec#

output: RhimeOutputSpec#

sites: tuple[str, ...]#

split_by_sectors: bool = False#

start_date: str#

class openghg_inversions.rhime.SectorSpec(name: str, flux_source: str, x_prior: dict[str, Any], variable_suffix: str)#

Bases: object

Configuration for one separately optimised flux sector.

Parameters:

name – User-facing sector name.
flux_source – OpenGHG flux source used to retrieve this sector.
x_prior – Prior specification for this sector’s flux scaling factors.
variable_suffix – PyMC-safe suffix used in model variable names.

flux_source: str#

name: str#

variable_suffix: str#

x_prior: dict[str, Any]#

openghg_inversions.rhime.make_multisector_flux_diagnostics(*, idata: InferenceData, prepared: _PreparedRhimeData, model_spec: RhimeModelSpec) → Dataset#

Create sector-aware posterior flux diagnostics for shared-basis RHIME.

Parameters:

idata – InferenceData returned by RHIME sampling.
prepared – Prepared RHIME data object containing basis and flux arrays.
model_spec – Model spec containing sector names and variable suffixes.

Returns:

Dataset containing posterior mean scaling factors, sector posterior flux means, and total posterior flux mean.

Load RHIME run parameters from an INI config file.

Parameters:

config_file – Path to an INI configuration file.
start_date – Optional command-line start-date override.
end_date – Optional command-line end-date override.
output_path – Optional command-line output-path override.
extra_kwargs – Optional keyword overrides, normally parsed from CLI JSON.

Returns:

Normalized RHIME run parameters using snake-case public names.

Raises:

ValueError – If deprecated unsupported parameters are present.

openghg_inversions.rhime.resolve_flux_sources(*, flux_sources: str | Sequence[str] | None = None, emissions_name: str | Sequence[str] | None = None) → list[str]#

Resolve new flux_sources and legacy emissions_name arguments.

Parameters:

flux_sources – Preferred OpenGHG flux source names.
emissions_name – Legacy name for flux sources.

Returns:

Resolved flux source names.

Raises:

ValueError – If no usable flux source is supplied.

openghg_inversions.rhime.run_rhime(*, config_file: str | Path | None = None, **kwargs: Any) → RhimeResult#

Run a standard single-sector RHIME inversion.

Parameters:

config_file – Optional INI configuration file. Values in kwargs override values read from this file.
**kwargs – RHIME run parameters using snake-case names, such as output_path, output_name, flux_sources, and x_prior.

Returns:

Modern RHIME result containing canonical inputs, InferenceData, specs, output metadata, and generated outputs.

Raises:

ValueError – If required parameters are missing, unsupported parameters are supplied, or the flux-source count is invalid.

openghg_inversions.rhime.run_rhime_multisector(*, config_file: str | Path | None = None, **kwargs: Any) → RhimeResult#

Run a shared-basis multi-sector RHIME inversion.

Parameters:

config_file – Optional INI configuration file. Values in kwargs override values read from this file.
**kwargs – RHIME run parameters using snake-case names. Multi-sector runs require at least two flux_sources and may include sector_priors keyed by flux source.

Returns:

Modern RHIME result containing canonical inputs, InferenceData, specs, output metadata, and sector diagnostics.

Raises:

ValueError – If required parameters are missing, unsupported parameters are supplied, or fewer than two flux sources are provided.