openghg_inversions.postprocessing.make_outputs#

class openghg_inversions.postprocessing.make_outputs.OutputSector(name: str, flux_source: str, variable_suffix: str)#

Bases: NamedTuple

Sector metadata needed for postprocessing reconstruction.

flux_source: str#: Alias for field number 1

name: str#: Alias for field number 0

variable_suffix: str#: Alias for field number 2

Create basic output with concentrations, flux totals, and country totals.

The dataset returned also contains the basis functions, and other data used to create the model, like “H matrices” and the flux used.

Parameters:

inv_out – inversion output to process
country_file – path to country file
country_regions – optional country regions to use. If “paris” is passed,
used. (then the PARIS regions will be)
stats – list of stats to use; if None, defaults to [“mean”,
"quantile"].
stats_args – optional arguments to pass to the stats functions.

Returns:

xr.Dataset containing statistics for concentrations, fluxes, and country totals.

openghg_inversions.postprocessing.make_outputs.convert_suffixes_to_dim(ds: Dataset, suffixes: list[str], new_dim: str) → Dataset#

openghg_inversions.postprocessing.make_outputs.flat_basis_for_output(inv_out: InversionOutput) → DataArray#: Return the retained flat basis map for output formats that still report one.

openghg_inversions.postprocessing.make_outputs.flatten_post_prior(ds: Dataset) → Dataset#

Add a dimension when that is either “post” or “prior”.

This reduces the number of data variables in the outputs.

Note: do this before flattening suffixes.

openghg_inversions.postprocessing.make_outputs.make_concentration_outputs(inv_out: InversionOutput, stats: list[str] | None = None, stats_args: dict | None = None, combine_bc_and_offset: bool = False) → Dataset#

Return dataset of stats for concentrations.

Parameters:

inv_out – Inversion output containing MCMC traces.
stats – List of stats to use. If None, the default for calculate_stats is used, which is “mean” and “quantiles”. See the postprocessing.stats submodule for more options.
stats_args – Dict of arguments to be passed to stats functions. If a key in this dict is the name of an argument for a stats function, then the value for this key will be passed to the stats function. To pass an option to a specific stats function, write the key in the form “<stat function name>__<key>”, with a double underscore. For instance, stats_args = {“mode_kde__chunk_size”: 20} would pass the argument chunk_size = 20 to the stat function mode_kde, and no others.
combine_bc_and_offset – If True, the offset is added to the baseline (before stats are calculated).

Returns:

xr.Dataset with computed flux stats.

Calculate country emission stats.

Parameters:

inv_out – Inversion output containing MCMC traces.
country_file – Path to country definition file. If None, the default country file location and the domain of the inversion output will be used to try to find a suitable country file.
country_selections – Optional country names or country codes to report.
country_regions – Dict mapping country region names (e.g. “BENELUX”) to a list of (country codes) of the countries comprising that regions (e.g. [“BEL”, “NLD”, “LUX”]).
stats – List of stats to use. If None, the default for calculate_stats is used, which is “mean” and “quantiles”. See the postprocessing.stats submodule for more options.
stats_args – Dict of arguments to be passed to stats functions. If a key in this dict is the name of an argument for a stats function, then the value for this key will be passed to the stats function. To pass an option to a specific stats function, write the key in the form “<stat function name>__<key>”, with a double underscore. For instance, stats_args = {“mode_kde__chunk_size”: 20} would pass the argument chunk_size = 20 to the stat function mode_kde, and no others.
country_code – If set to “alpha2” or “alpha3”, country names will be converted to two or three digit country codes, respectively. Country region definitions should use the same type of code as specified here.

Returns:

xr.Dataset containing statistics for the specified countries and regions.

openghg_inversions.postprocessing.make_outputs.make_flux_outputs(inv_out: InversionOutput, stats: list[str] | None = None, stats_args: dict | None = None, include_scale_factors: bool = True, report_flux_on_inversion_grid: bool = True) → Dataset#

Return dataset of stats for fluxes and scaling factors.

Parameters:

inv_out – Inversion output containing MCMC traces.
stats – List of stats to use. If None, the default for calculate_stats is used, which is “mean” and “quantiles”. See the postprocessing.stats submodule for more options.
stats_args – Dict of arguments to be passed to stats functions. If a key in this dict is the name of an argument for a stats function, then the value for this key will be passed to the stats function. To pass an option to a specific stats function, write the key in the form “<stat function name>__<key>”, with a double underscore. For instance, stats_args = {“mode_kde__chunk_size”: 20} would pass the argument chunk_size = 20 to the stat function mode_kde, and no others.
include_scale_factors – If True, report stats for scale factors, in addition to stats for fluxes (which are calculated by transforming the scale factor stats to the lat/lon grid using the prior flux).
report_flux_on_inversion_grid – If True, report fluxes by basis function, without incorporating the prior flux. Note: we do not actually optimise for this quantity, since the prior flux is used in the forward model.

Returns:

xr.Dataset with computed flux stats.

openghg_inversions.postprocessing.make_outputs.make_multisector_country_trace_outputs(inv_out: InversionOutput, countries: Countries) → Dataset#

Map multisector scaling traces directly from basis regions to countries.

The country projection is formed independently for each sector using that sector’s retained basis operator and prior flux. Applying the projection to the scaling traces avoids reconstructing draw-wise latitude/longitude flux fields solely to calculate country totals.

Parameters:

inv_out – Multisector inversion output containing sector scaling traces, retained basis functions, prior fluxes, and species metadata.
countries – Country masks and grid-cell areas aligned with the retained flux grid.

Returns:

Lazy or sparse-compatible prior and posterior country traces in grams per year. Variables are named country_<sector>_<when> plus summed country_total_<when> variables.

Raises:

ValueError – If the inversion is not multisector or required sector or species metadata is missing.

openghg_inversions.postprocessing.make_outputs.make_multisector_flux_trace_outputs(inv_out: InversionOutput, report_flux_on_inversion_grid: bool = True, *, materialize: bool = True) → Dataset#

Return per-draw reconstructed sector and total multisector flux traces.

Parameters:

inv_out – Inversion output containing multisector MCMC traces and retained basis functions.
report_flux_on_inversion_grid – If true, reconstruct values on the reduced inversion grid; otherwise include the sector prior flux on the latitude/longitude grid.
materialize – If true, convert the completed trace to NumPy-backed arrays. Set this to false when a downstream labelled reduction can preserve lazy or sparse arrays. The default preserves the historical return boundary.

Returns:

Per-draw total and sector flux traces with reconstruction metadata.

Raises:

ValueError – If inv_out is not multisector or lacks required sector metadata or trace variables.

openghg_inversions.postprocessing.make_outputs.make_sector_flux_outputs(inv_out: InversionOutput, stats: list[str] | None = None, stats_args: dict | None = None, include_scale_factors: bool = True, report_flux_on_inversion_grid: bool = True) → Dataset#: Return multisector flux statistics by sector plus correctly reconstructed total flux statistics.

openghg_inversions.postprocessing.make_outputs.model_error_output(inv_out: InversionOutput) → DataArray#: Return the inferred model-error component for basic/PARIS products.

openghg_inversions.postprocessing.make_outputs.observation_and_error_outputs(inv_out: InversionOutput) → Dataset#: Return observations and derived uncertainty terms for current products.

openghg_inversions.postprocessing.make_outputs.observation_inputs_for_outputs(inv_out: InversionOutput) → Dataset#: Return observation inputs named for current basic/PARIS product helpers.

openghg_inversions.postprocessing.make_outputs.sort_data_vars(ds: Dataset) → Dataset#: Sort data variables by variable name, then suffix.

openghg_inversions.postprocessing.make_outputs.total_error_output(inv_out: InversionOutput, take_mean: bool = True) → DataArray#: Return the posterior model-data mismatch error for basic/PARIS products.