openghg_inversions.inversion_data#

class openghg_inversions.inversion_data.FixedBasisPreparedData(fp_all: dict, fp_data: dict | None = None, inv_inputs: Dataset | None = None, sites: list[str] = <factory>, averaging_period: list[str | None] = <factory>, basis_objects: dict[str, ~openghg_inversions.basis.basis_functions.FluxWeightedBasis]=<factory>, basis_artifact_source: str = 'generated', basis_artifact_path: str | None = None)#

Bases: object

Data prepared for the legacy fixedbasis runner.

Parameters:

fp_all – Raw merged-data container returned by data gathering or reload.
fp_data – Forward-model data after basis functions and filters.
inv_inputs – Canonical inversion inputs consumed by model builders.
sites – Retained site names after data gathering and filtering.
averaging_period – Averaging periods aligned to retained sites.
basis_objects – Basis objects returned by basis_functions_wrapper.
basis_artifact_source – Source of the flux basis artifact.
basis_artifact_path – Path to the flux basis artifact, when loaded or saved.

averaging_period: list[str | None]#

basis_artifact_path: str | None = None#

basis_artifact_source: str = 'generated'#

basis_objects: dict[str, FluxWeightedBasis]#

fp_all: dict#

fp_data: dict | None = None#

inv_inputs: Dataset | None = None#

sites: list[str]#

class openghg_inversions.inversion_data.RhimePreparedInputs(inv_inputs: Dataset, basis_functions: FluxWeightedBasis, sites: tuple[str, ...], averaging_period: tuple[str | None, ...], basis_artifact_source: str, basis_artifact_path: str | None = None, site_lats: tuple[float, ...] | None = None, site_lons: tuple[float, ...] | None = None)#

Bases: object

Modern RHIME preparation contract.

Parameters:

inv_inputs – Canonical inversion inputs consumed by RHIME model builders.
basis_functions – Retained flux basis object used to derive output-boundary basis and flux arrays.
sites – Retained site names after data gathering and filtering.
averaging_period – Averaging periods aligned to retained sites.
basis_artifact_source – Description of whether the basis was generated or loaded from an artifact.
basis_artifact_path – Path to the basis artifact, when loaded or saved.
site_lats – Release latitudes aligned to sites, when available.
site_lons – Release longitudes aligned to sites, when available.

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

basis_artifact_path: str | None = None#

basis_artifact_source: str#

basis_functions: FluxWeightedBasis#

inv_inputs: Dataset#

site_lats: tuple[float, ...] | None = None#

site_lons: tuple[float, ...] | None = None#

sites: tuple[str, ...]#

Retrieve and prepare fixed-surface datasets from specified OpenGHG object stores.

Use for forward simulations and model-data comparisons that do not use tracers.

Parameters:

species – Atmospheric trace gas species of interest e.g. “co2”
sites – List of strings containing measurement station/site abbreviations e.g. [“MHD”, “TAC”] NOTE: for satellite, pass as “satellitename-obs_region” eg “GOSAT-BRAZIL” and pass corresponding platform as “satellite”
domain – Model domain region of interest; e.g. “EUROPE”
averaging_period – List of averaging periods to apply to mole fraction data. NB. len(averaging_period)==len(sites) e.g. [“1H”, “1H”]
start_date – Date from which to gather data; e.g. “2020-01-01”
end_date – Date until which to gather data; e.g. “2020-02-01”
obs_data_level – ICOS observations data level. For non-ICOS sites use “None”
inlet – Specific inlet height for the site observations (length must match number of sites)
instrument – Specific instrument for the site (length must match number of sites)
max_level – Maximum atmospheric level to extract. Only needed if using satellite/site-column data.
calibration_scale – Convert measurements to defined calibration scale
met_model – Meteorological model used in the LPDM. List must be same length as number of sites.
fp_model – LPDM used for generating footprints.
fp_height – Inlet height used in footprints for corresponding sites.
fp_species – Species name associated with footprints in the object store
emissions_name – List of keywords args associated with emissions files in the object store. Corresponds to source in OpenGHG.
use_bc – Option to include boundary conditions in model
bc_input – Variable for calling BC data from ‘bc_store’ - equivalent of ‘emissions_name’ for fluxes.
bc_store – Name of object store to retrieve boundary conditions data from.
obs_store – Name of object store to retrieve observations data from.
footprint_store – Name of object store to retrieve footprints data from.
emissions_store – Name of object store to retrieve emissions data from.
flux_non_finite_check – Non-finite flux handling mode. "lazy" applies zero-fill lazily and records attrs; "count" computes count metadata once and warns if non-finite values are present.
split_by_sectors – If True, calculate sector-resolved fp_x_flux_sectoral in ModelScenario. If False (default), combine all flux sources into a single fp_x_flux pathway.
averagingerror – Adds the variability in the averaging period to the measurement error if set to True.
save_merged_data – Save forward simulations data and observations.
merged_data_name – Filename for saved forward simulations data and observations.
merged_data_dir – Directory path for for saved forward simulations data and observations.
output_name – Optional name used to create merged data name.

Returns:

containing

fp_all: dictionary containing flux data (key “.flux”), bc data (key “.bc”), and observations data (site short name as key)

sites: Updated list of sites. All put in upper case and if data was not extracted correctly for any sites, drop these from the rest of the inversion.

inlet: List of inlet height for the updated list of sites

fp_height: List of footprint height for the updated list of sites

instrument: List of instrument for the updated list of sites

averaging_period: List of averaging_period for the updated list of sites

Return type:

tuple

openghg_inversions.inversion_data.load_merged_data(merged_data_dir: str | Path, species: str | None = None, start_date: str | None = None, output_name: str | None = None, merged_data_name: str | None = None, output_format: Literal['pickle', 'netcdf', 'zarr', 'zarr.zip'] | None = None) → dict#

Load fp_all dictionary from a file in merged_data_dir.

The name of the pickle file can be specified using merged_data_name, or a standard name will be created given species, start_date, and output_name.

If merged_data_name is not given, then species, start_date, and output_name must be provided.

This function tries to automatically find a compatible format of merged data, if a format is not specified. First, it checks for data in “zarr” (or zipped zarr) format, then in netCDF, and finally in pickle.

Note: if data is stored in a zarr ZipStore, then the data is eagerly loaded, since the data needs to loaded before the zip file is closed.

Parameters:

merged_data_dir – path to directory where merged data will be saved
species – species of inversion
start_date – start date of inversion period
output_name – output name parameter used for inversion run
merged_data_name – name to use for saved data.
output_format – format of data to load (if not specified, this will be inferred).

Returns:

fp_all dictionary

openghg_inversions.inversion_data.prepare_fixedbasis_inversion_data(*, species: str, sites: list[str], domain: str, averaging_period: list[str | None] | str | None, start_date: str, end_date: str, output_name: str, flux_sources: list[str] | None, split_by_sectors: bool = False, bc_store: str = 'user', obs_store: str = 'user', footprint_store: str = 'user', emissions_store: str = 'user', met_model: Any = None, fp_model: str | None = None, fp_height: Any = None, fp_species: str | None = None, inlet: Any = None, instrument: Any = None, max_level: int | None = None, calibration_scale: str | None = None, obs_data_level: Any = None, platform: Any = None, use_tracer: bool = False, use_bc: bool = True, fp_basis_case: str | None = None, basis_directory: str | None = None, bc_basis_case: str = 'NESW', bc_basis_directory: str | Path | None = None, country_directory: str | None = None, bc_input: str | None = None, basis_algorithm: str = 'weighted', nbasis: int = 100, filters: Any = None, fix_basis_outer_regions: bool = False, averaging_error: bool = True, bc_freq: str | None = None, sigma_freq: str | None = None, reload_merged_data: bool = False, save_merged_data: bool = False, merged_data_dir: str | None = None, merged_data_name: str | None = None, basis_output_path: str | None = None, min_error: Literal['percentile', 'residual'] | dict[str, float] | None | int | float = 0.0, calculate_min_error: Literal['percentile', 'residual'] | None = None, min_error_options: dict | None = None, return_basis_objects: bool = False, merged_data_only: bool = False, flux_non_finite_check: Literal['lazy', 'count'] = 'lazy') → FixedBasisPreparedData#: Prepare data for legacy fixedbasisMCMC and its output adapters.

openghg_inversions.inversion_data.prepare_rhime_inputs(*, species: str, sites: list[str], domain: str, averaging_period: list[str | None] | str | None, start_date: str, end_date: str, output_name: str, flux_sources: list[str], split_by_sectors: bool = False, bc_store: str = 'user', obs_store: str = 'user', footprint_store: str = 'user', emissions_store: str = 'user', met_model: Any = None, fp_model: str | None = None, fp_height: Any = None, fp_species: str | None = None, inlet: Any = None, instrument: Any = None, max_level: int | None = None, calibration_scale: str | None = None, obs_data_level: Any = None, platform: Any = None, use_tracer: bool = False, use_bc: bool = True, fp_basis_case: str | None = None, basis_directory: str | None = None, bc_basis_case: str = 'NESW', bc_basis_directory: str | Path | None = None, country_directory: str | None = None, bc_input: str | None = None, basis_algorithm: str = 'weighted', nbasis: int = 100, filters: Any = None, fix_basis_outer_regions: bool = False, averaging_error: bool = True, bc_freq: str | None = None, sigma_freq: str | None = None, reload_merged_data: bool = False, save_merged_data: bool = False, merged_data_dir: str | None = None, merged_data_name: str | None = None, basis_output_path: str | None = None, min_error: Literal['percentile', 'residual'] | dict[str, float] | None | int | float = 0.0, min_error_options: dict | None = None, flux_non_finite_check: Literal['lazy', 'count'] = 'lazy') → RhimePreparedInputs#

Prepare modern RHIME inputs without exposing legacy fixedbasis containers.

Parameters:

species – Primary gas or tracer name used for object-store lookup and output naming.
sites – Requested observation site names.
domain – Model domain name.
averaging_period – Observation averaging period, either scalar or site-aligned.
start_date – Inclusive inversion start date.
end_date – Exclusive inversion end date.
output_name – Base output name used for data and basis artifacts.
flux_sources – OpenGHG flux source values requested for the run.
split_by_sectors – Whether to keep sector-resolved sensitivity inputs with a source coordinate.
use_tracer – Unsupported placeholder for tracer inversions, where an additional species constrains the primary species through linked forward models.
flux_non_finite_check – Non-finite flux handling mode. "lazy" applies zero-fill lazily and records attrs; "count" computes count metadata once and warns if non-finite values are present.

Returns:

Modern RHIME prepared inputs containing canonical inv_inputs and a retained BasisFunctions object.