openghg_inversions.basis#

Basis construction, projection, and retained covariance-product interfaces.

The package provides basis-generation functions, flux-weighted preparation wrappers, prior-width projection helpers, and the public OPE-17 retained covariance-product API.

Basis operators own grid/state geometry: their bucket matrix is a prolongation from retained scalings to the native grid, not an automatic retained restriction. FluxWeightedBasis, exported here as BasisFunctions, pairs that geometry with flux for sensitivity projection and reconstruction; it does not own native covariance transforms. Project-owned workflows can compose the basis algorithms and use basis_functions_from_fp_all_flat_basis to attach current-run flux without importing private preparation functions.

Native covariance actions live in openghg_inversions.native_covariance and openghg_inversions.source_covariance. The interfaces re-exported here choose a compatible restriction/prolongation pair and prepare labelled product blocks. They are low-level inputs to openghg_inversions.coherent_reduction and do not themselves construct the centred reduced likelihood or unresolved covariance.

openghg_inversions.basis.BasisFunctions#: alias of FluxWeightedBasis

class openghg_inversions.basis.NativeCovarianceProducts(restriction: DataArray, prolongation: DataArray, state_covariance: DataArray, effective_observation_operator: DataArray, observation_state_cross_covariance: DataArray, native_observation_covariance: DataArray, strategy: str, observation_covariance_view: Literal['dense', 'diagonal'])#

Bases: object

Labelled in-memory product blocks induced by one retained restriction.

Variables:

restriction (xarray.core.dataarray.DataArray) – Dimensionless Pi with dimensions (state_dim, *native_dims).
prolongation (xarray.core.dataarray.DataArray) – Derived dimensionless covariance-natural U_* with dimensions (*native_dims, state_dim).
state_covariance (xarray.core.dataarray.DataArray) – Positive-definite dimensionless C_alpha with distinct typed row/column state dimensions.
effective_observation_operator (xarray.core.dataarray.DataArray) – H U_* with dimensions (observation_dim, state_dim) and sensitivity units.
observation_state_cross_covariance (xarray.core.dataarray.DataArray) – H B Pi.T with dimensions (observation_dim, state_column_dim) and sensitivity units.
native_observation_covariance (xarray.core.dataarray.DataArray) – Dense positive-semidefinite (and possibly singular) H B H.T on distinct typed observation axes, or its nonnegative observation-axis diagonal. Units are squared sensitivity units.
strategy (str) – Identifier of the strategy that selected Pi.
observation_covariance_view (Literal['dense', 'diagonal']) – Whether the observation covariance field contains the dense matrix or its diagonal.

Notes

Freezing the dataclass prevents field reassignment, but the contained DataArrays remain mutable. Product attributes are construction-time snapshots, not live views of input attribute mappings.

effective_observation_operator: DataArray#

native_observation_covariance: DataArray#

observation_covariance_view: Literal['dense', 'diagonal']#

observation_state_cross_covariance: DataArray#

prolongation: DataArray#

restriction: DataArray#

state_covariance: DataArray#

strategy: str#

class openghg_inversions.basis.PreserveBucketProlongation(name: str = 'preserve_bucket_prolongation')#

Bases: object

Derive Pi_U so covariance-weighted prolongation equals U_bucket.

name: str#

projection(covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, *, native_dims: tuple[str, ...], state_dim: str) → RetainedProjection#

Construct the prior-precision-compatible restriction.

Parameters:

covariance – Invertible labelled action for native covariance B.
basis_prolongation – Eager canonical bucket prolongation U.
native_dims – Ordered native dimensions.
state_dim – Retained-state dimension.

Returns:

The authoritative bucket-compatible restriction Pi_U.

Raises:

ValueError – If U is invalid or lacks full column rank.

class openghg_inversions.basis.RetainedProjection(restriction: DataArray, strategy: str)#

Bases: object

A labelled retained restriction selected by one strategy.

Variables:

restriction (xarray.core.dataarray.DataArray) – Dimensionless Pi with dimensions (state_dim, *native_dims). The frozen dataclass does not freeze this mutable DataArray.
strategy (str) – Stable identifier for the scientific projection choice.

restriction: DataArray#

strategy: str#

class openghg_inversions.basis.RetainedProjectionStrategy(*args, **kwargs)#

Bases: Protocol

Extension seam for choosing authoritative retained coefficients.

projection(covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, *, native_dims: tuple[str, ...], state_dim: str) → RetainedProjection#

Return the authoritative labelled retained restriction Pi.

Parameters:

covariance – Labelled native covariance action.
basis_prolongation – Dimensionless basis U with dimensions (*native_dims, state_dim).
native_dims – Ordered native covariance dimensions.
state_dim – Retained-state dimension.

Returns:

A dimensionless restriction with dimensions (state_dim, *native_dims). The kernel derives B Pi.T, C_alpha, and U_* from it.

openghg_inversions.basis.basis_functions_from_fp_all_flat_basis(*, fp_all: dict, basis_flat: DataArray | Mapping[str, DataArray], metadata: Mapping[str, Any] | None = None) → FluxWeightedBasis#

Compatibility adapter that constructs a basis object from flat basis data.

This is also the public handoff for project-owned flat-basis algorithms in copied RHIME runners. A single two-dimensional array defines a shared spatial basis. A source-keyed mapping defines source-specific bases and is restricted and ordered to match runtime flux sources when fp_all is sector resolved. In both cases the retained flux is reconstructed from the current fp_all input rather than from the flat-basis producer.

Parameters:

fp_all – Legacy merged-data dictionary containing a ".flux" side channel and optional ".split_by_sectors" flag.
basis_flat – Two-dimensional shared flat basis array, or source-keyed two-dimensional flat basis arrays, produced by a compatible basis algorithm or legacy loading path.
metadata – Optional namespaced metadata to carry on the basis object.

Returns:

A retained BasisFunctions object with flux reconstructed from fp_all.

Raises:

TypeError – If a runtime flux entry or basis input has an unsupported type.
ValueError – If runtime flux is missing or inconsistent, a source-specific basis omits a runtime source, or basis labels and dimensions violate the retained-basis contract.
xarray.AlignmentError – If basis and current-run flux grids are not physically compatible.

openghg_inversions.basis.basis_functions_wrapper(fp_all: dict, species: str, domain: str, start_date: str, emissions_name: list[str] | None, nbasis: int, use_bc: bool, basis_algorithm: str | None = None, fix_outer_regions: bool = False, fp_basis_case: str | None = None, bc_basis_case: str | None = None, basis_directory: str | None = None, bc_basis_directory: str | None = None, country_directory: str | None = None, outputname: str | None = None, output_path: str | None = None, return_basis_objects: bool = False, basis_output_format: Literal['legacy', 'datatree'] = 'legacy', region_classes: DataArray | None = None, region_allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_acceptance: Literal['none', 'contrast_score'] = 'none', contrast_contribution: DataArray | None = None, contrast_cell_weight: DataArray | None = None, min_contrast_delta_eig: float | None = None, min_contrast_lambda: float | None = None, contrast_tau: float | None = None, contrast_sigma_design: float | None = None, contrast_s_diag: DataArray | None = None)#

Create basis sensitivities for a legacy fixed-basis inversion.

Parameters:

fp_all – Legacy merged-data dictionary containing flux and footprint data.
species – Atmospheric trace gas species used when saving generated basis artifacts.
domain – Inversion domain.
start_date – Start date of the inversion period.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Desired number of generated basis regions.
use_bc – If true, include boundary-condition sensitivities.
basis_algorithm – Algorithm used when generating a basis field on the fly. "quadtree" does not impose land/sea separation, "weighted" uses the legacy weighted land/sea split, and "region_constrained" requires caller-supplied region_classes to prevent labels crossing those classes.
fix_outer_regions – If true, use fixed InTEM outer regions and generate basis labels only for the inner region.
fp_basis_case – Optional saved emissions basis case. When supplied, a saved artifact is loaded instead of generating a basis.
bc_basis_case – Boundary-condition basis case to load when use_bc is true.
basis_directory – Optional root directory for saved emissions basis artifacts.
bc_basis_directory – Optional root directory for saved boundary-condition basis artifacts.
country_directory – Optional directory containing auxiliary land/sea and InTEM outer-region files used by generated basis algorithms.
outputname – Optional output-name component used when saving generated basis artifacts.
output_path – Optional directory where generated basis artifacts should be saved.
return_basis_objects – If true, return the legacy fp_data dictionary plus retained basis objects.
basis_output_format – Format for saved generated basis artifacts. "legacy" writes the historical flat netCDF file, while "datatree" writes the retained BasisFunctions artifact.
region_classes – Two-dimensional class field used only with basis_algorithm="region_constrained". Loading this field from a file is the caller’s responsibility.
region_allocation – Automatic class-allocation mode for region_constrained. One of "weight" or "area".
min_regions_per_class – Minimum automatic allocation for each non-empty mapped class when using region_constrained.
split_acceptance – Optional split-acceptance criterion for region_constrained. Defaults to "none" to preserve existing behavior.
contrast_contribution – Design contribution array for contrast scoring; do not use observed mole-fraction values or residuals.
contrast_cell_weight – Optional prior flux or split-mass field for contrast scoring.
min_contrast_delta_eig – Optional minimum contrast delta_eig.
min_contrast_lambda – Optional minimum contrast lambda.
contrast_tau – Prior standard deviation of the split contrast coefficient. If omitted, tau=1 is uncalibrated.
contrast_sigma_design – Optional scalar design standard deviation.
contrast_s_diag – Optional diagonal design covariance entries.

Returns:

By default, returns a dictionary similar to fp_all but with basis function and sensitivity data added. If return_basis_objects=True, returns (fp_data, basis_objects) where basis_objects["emissions"] is the retained emissions BasisFunctions object.

Raises:

ValueError – If boundary conditions are requested without bc_basis_case.

openghg_inversions.basis.basis_weights_from_fp_all(fp_all: dict, emissions_name: list[str] | None = None, *, abs_flux: bool = False, mask: DataArray | None = None) → DataArray#

Build the standard 2D basis weight field from a legacy fp_all mapping.

The generated basis algorithms historically computed weights internally from mean footprints multiplied by mean flux. This helper exposes that adapter step so algorithms and experiments can use already computed weight fields directly.

Parameters:

fp_all – Legacy merged-data dictionary produced by the data preparation path.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
abs_flux – If true, use absolute flux values before averaging.
mask – Optional Boolean spatial mask. When supplied, weights outside the mask are dropped from the returned field.

Returns:

Two-dimensional weight field with spatial coordinates preserved.

openghg_inversions.basis.bucket_basis_from_weights(weights: DataArray, start_date: str, domain: str, *, nbasis: int = 100, country_directory: str | None = None) → DataArray#

Create a legacy weighted bucket basis field from precomputed 2D weights.

This is a weight-first version of bucket_basis_function(). It still delegates to the existing land/sea-aware weighted algorithm for compatibility.

Parameters:

weights – Two-dimensional basis weight field.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
nbasis – Desired number of basis regions.
country_directory – Optional directory containing land/sea files.

Returns:

Basis field with lat/lon dimensions, a singleton time dimension, and integer region labels.

openghg_inversions.basis.bucket_basis_function(fp_all: dict, start_date: str, domain: str, emissions_name: list[str] | None = None, nbasis: int = 100, country_directory: str | None = None, abs_flux: bool = False, mask: DataArray | None = None) → DataArray#

Create a basis field with the legacy weighted bucket algorithm.

This algorithm recursively splits weighted rectangles so each scaling region contains approximately the same total weight. The implementation also uses land/sea masks from country_directory through the lower-level weighted algorithm.

Parameters:

fp_all – Legacy merged-data dictionary produced by the data preparation path.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Desired number of basis regions.
country_directory – Optional directory containing land/sea files. When omitted, default package files are used.
abs_flux – If true, use absolute flux values when constructing weights.
mask – Optional Boolean spatial mask for fitting basis functions over a sub-region.

Returns:

Basis field with lat/lon dimensions, a singleton time dimension, and integer region labels.

openghg_inversions.basis.bucketbasisfunction(*args, **kwargs) → DataArray#: Deprecated alias for bucket_basis_function().

openghg_inversions.basis.calibrate_basis_prior_stdev(basis_functions: FluxWeightedBasis, *, area_grid: DataArray, target_matrix: DataArray, target_relative_stdev: DataArray | float, target_statistic: Literal['median-relative', 'mean-total'] = 'median-relative', state_is_active: DataArray | None = None, flux: DataArray | None = None) → Dataset#

Calibrate grid-cell and basis-state prior widths to aggregate targets.

Calibration first projects a unit grid-cell standard deviation. For each source, linearity then gives the cell standard deviation required to match either the median target-relative SD or the ratio of mean target SD to mean absolute target total. A scalar target request is shared; a source-labelled request is selected by label. With one target per source, either statistic matches the requested value exactly.

target_matrix may contain any caller-defined target dimensions in addition to the operator grid. No countries, masks, or target percentages are built into this API.

The result includes grid_cell_prior_stdev, x_prior_stdev, state and target totals, achieved target standard deviations, achieved relative standard deviations, and explicit state/target/calibration status strings. Status zero means the target contains no absolute weighted flux; cancellation means nonzero signed weights sum to a zero target total; state_cancellation means a target depends on a basis state whose own signed total cancels to zero.

Parameters:

basis_functions – Retained basis artifact and operator.
area_grid – Grid-cell areas on the operator grid.
target_matrix – Caller-defined target masks or weights.
target_relative_stdev – Requested relative standard deviation, scalar or source-labelled.
target_statistic – Aggregate calibration statistic, either "median-relative" or "mean-total".
state_is_active – Optional labelled Boolean state mask. Inactive state widths are set to zero and omitted from target uncertainty, matching active-state model sampling.
flux – Optional replacement flux. The retained flux is used by default.

Returns:

Dataset containing calibrated widths and projection diagnostics.

openghg_inversions.basis.fixed_outer_regions_basis(fp_all: dict, start_date: str, basis_algorithm: str, domain: str, emissions_name: list[str] | None = None, nbasis: int = 100, country_directory: str | None = None, abs_flux: bool = False, *, region_classes: DataArray | None = None, region_allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_acceptance: Literal['none', 'contrast_score'] = 'none', contrast_contribution: DataArray | None = None, contrast_cell_weight: DataArray | None = None, min_contrast_delta_eig: float | None = None, min_contrast_lambda: float | None = None, contrast_tau: float | None = None, contrast_sigma_design: float | None = None, contrast_s_diag: DataArray | None = None) → DataArray#

Use fixed InTEM outer regions and fit inner regions with an algorithm.

The InTEM outer-region file defines known outer labels. The largest region value is treated as the inner inversion region; this inner mask is passed to basis_algorithm and then inserted back into the fixed outer map.

Parameters:

fp_all – Legacy merged-data dictionary produced by the data preparation path.
start_date – Start date of the inversion period.
basis_algorithm – Algorithm used to fit the inner region. Supported values are "quadtree", "weighted", and "region_constrained".
domain – Domain across which to calculate basis functions.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Desired number of inner-region basis labels.
country_directory – Optional directory containing land/sea files and the InTEM outer-region file. When omitted, default package files are used.
abs_flux – If true, use absolute flux values when constructing weights.
region_classes – Region or country class field used only with basis_algorithm="region_constrained". File loading should happen before calling this helper.
region_allocation – Allocation mode for region_constrained. One of "weight" or "area".
min_regions_per_class – Minimum automatic allocation for each non-empty mapped class when using region_constrained.
split_acceptance – Optional split-acceptance criterion for region_constrained inner-region splitting.
contrast_contribution – Design contribution array used only when split_acceptance="contrast_score".
contrast_cell_weight – Optional prior flux or split-mass field used for contrast scoring.
min_contrast_delta_eig – Optional minimum contrast delta_eig.
min_contrast_lambda – Optional minimum contrast lambda.
contrast_tau – Prior standard deviation of the split contrast coefficient. If omitted, tau=1 is uncalibrated.
contrast_sigma_design – Optional scalar design standard deviation.
contrast_s_diag – Optional diagonal design covariance entries.

Returns:

Basis field with fixed outer labels and generated inner labels.

openghg_inversions.basis.load_basis_functions(*, fp_all: dict, domain: str, basis_case: str, basis_directory: str | Path | None = None) → FluxWeightedBasis#

Load a saved basis artifact as retained BasisFunctions.

DataTree artifacts are preferred when the matching file carries the openghg_inversions.flux_weighted_basis schema and are loaded through BasisFunctions.load. Otherwise the existing legacy flat artifact loader is used and a retained basis object is built from runtime flux in fp_all.

Parameters:

fp_all – Legacy merged-data dictionary used to build runtime flux when adapting legacy flat artifacts or replacing serialized DataTree flux.
domain – Inversion domain used in the artifact path convention.
basis_case – Basis case prefix used in the artifact path convention.
basis_directory – Optional root directory containing per-domain basis artifact subdirectories.

Returns:

Loaded retained basis object with basis_artifact_source metadata.

Raises:

FileNotFoundError – If no matching artifact files are found.
ValueError – If more than one matching DataTree artifact is found.

openghg_inversions.basis.load_country_region_classes(domain: str, country_directory: str | Path | None = None) → DataArray#

Load a coordinate-preserving country or land/sea class map.

The path-selection behavior matches the legacy weighted-basis loader. A caller-supplied directory uses country-land-sea_{domain}.nc. Packaged EUROPE data use country-EUROPE-UKMO-landsea-2023.nc; other packaged domains use country-land-sea_{domain}.nc and fall back to the EUROPE file when that domain file is unavailable. Values are returned unchanged: every distinct non-null value can be used as a separate region class, so a caller-supplied multi-country integer map is not coerced to binary.

Parameters:

domain – Domain used to select the country/land-sea file.
country_directory – Optional directory containing the class-map file.

Returns:

Loaded two-dimensional country field with its original values, spatial coordinates, and metadata.

Raises:

FileNotFoundError – If the selected file does not exist.
KeyError – If the selected dataset does not contain country.

openghg_inversions.basis.load_intem_outer_regions(domain: str, outer_regions_path: str | Path | None = None) → DataArray#

Load a coordinate-preserving InTEM fixed-outer region map.

Parameters:

domain – Domain suffix used to select outer_region_definition_{domain}.nc when outer_regions_path is omitted.
outer_regions_path – Optional direct path to an outer-region NetCDF file. When omitted, the packaged file for domain in openghg_inversions.basis is used.

Returns:

Loaded two-dimensional region field, including its spatial coordinates and metadata.

Raises:

FileNotFoundError – If the selected region file does not exist.
KeyError – If the selected dataset does not contain region.

openghg_inversions.basis.make_basis_functions(*, fp_all: dict, species: str, domain: str, start_date: str, emissions_name: list[str] | None, nbasis: int, basis_algorithm: str | None = None, fix_outer_regions: bool = False, fp_basis_case: str | None = None, basis_directory: str | None = None, country_directory: str | None = None, outputname: str | None = None, output_path: str | None = None, basis_output_format: Literal['legacy', 'datatree'] = 'legacy', region_classes: DataArray | None = None, region_allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_acceptance: Literal['none', 'contrast_score'] = 'none', contrast_contribution: DataArray | None = None, contrast_cell_weight: DataArray | None = None, min_contrast_delta_eig: float | None = None, min_contrast_lambda: float | None = None, contrast_tau: float | None = None, contrast_sigma_design: float | None = None, contrast_s_diag: DataArray | None = None) → FluxWeightedBasis#

Create or load retained emissions basis functions.

This helper owns basis artifact generation/loading without applying the legacy fixedbasis fp_data side channels.

Parameters:

fp_all – Legacy merged-data dictionary containing flux and footprint data.
species – Atmospheric trace gas species used when saving generated basis artifacts.
domain – Inversion domain used for generated basis metadata and basis artifact lookup.
start_date – Start date of the inversion period.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Desired number of generated basis regions.
basis_algorithm – Algorithm used when generating a basis field on the fly. Supported values are "quadtree", "weighted", and "region_constrained".
fix_outer_regions – If true, use fixed InTEM outer regions and generate basis labels only for the inner region.
fp_basis_case – Optional saved emissions basis case. When supplied, a saved artifact is loaded instead of generating a basis.
basis_directory – Optional root directory for saved emissions basis artifacts.
country_directory – Optional directory containing auxiliary land/sea and InTEM outer-region files used by generated basis algorithms.
outputname – Optional output-name component used when saving generated basis artifacts.
output_path – Optional directory where generated basis artifacts should be saved.
basis_output_format – Format for saved generated basis artifacts. "legacy" writes the historical flat netCDF file, while "datatree" writes the retained BasisFunctions artifact.
region_classes – Two-dimensional class field used only with basis_algorithm="region_constrained". Loading this field from a file is the caller’s responsibility.
region_allocation – Automatic class-allocation mode for region_constrained. One of "weight" or "area".
min_regions_per_class – Minimum automatic allocation for each non-empty mapped class when using region_constrained.
split_acceptance – Optional split-acceptance criterion for region_constrained. Defaults to "none" to preserve existing behavior. "contrast_score" requires contrast_contribution.
contrast_contribution – Design contribution array for contrast scoring; do not use observed mole-fraction values or residuals.
contrast_cell_weight – Optional prior flux or split-mass field for contrast scoring.
min_contrast_delta_eig – Optional minimum contrast delta_eig.
min_contrast_lambda – Optional minimum contrast lambda.
contrast_tau – Prior standard deviation of the split contrast coefficient. If omitted, tau=1 is uncalibrated.
contrast_sigma_design – Optional scalar design standard deviation.
contrast_s_diag – Optional diagonal design covariance entries.

Returns:

Retained emissions basis object ready for sensitivity projection.

Raises:

ValueError – If neither a saved basis case nor an algorithm is supplied, or if an unsupported output format or basis algorithm is requested.
TypeError – If a generated algorithm returns an unsupported basis object.

openghg_inversions.basis.paired_abs_response_weights(flux: DataArray, footprints: list[DataArray], *, mask: DataArray | None = None) → DataArray#

Build weights from retained footprint observations paired with prior flux.

Each retained footprint time is multiplied by the prior flux at the same timestamp, and absolute responses are averaged over retained observations: mean_o(abs(fp_o * flux_at_o)). This helper is intentionally pure and lower-level; callers are responsible for passing footprints after any observation filters have been applied.

Parameters:

flux – Prior flux field with time plus spatial dimensions.
footprints – Retained footprint fields for each site.
mask – Optional Boolean spatial mask. When supplied, weights outside the mask are dropped from the returned field.

Returns:

Two-dimensional response weight field with spatial coordinates preserved.

Raises:

ValueError – If no footprints are supplied, required time dimensions are absent, or a retained footprint time cannot be paired with a flux time. Also raised when paired arrays do not have exactly two matching spatial dimensions and coordinates, or when a mask is not Boolean and defined on those spatial dimensions.

openghg_inversions.basis.project_basis_prior_stdev(basis_functions: FluxWeightedBasis, *, area_grid: DataArray, grid_cell_prior_stdev: DataArray | float, flux: DataArray | None = None) → DataArray#

Project independent grid-cell scale uncertainty onto basis states.

For membership matrix A and cell-total weights w = flux * area, the projected standard deviation is

sqrt(sum(A * (w * s)**2)) / abs(sum(A * w)).

s may be scalar, source-labelled, or gridded. A state with no weighted flux receives zero standard deviation. A state whose signed total cancels to zero while its numerator is nonzero receives NaN because its multiplicative scale uncertainty is undefined.

Parameters:

basis_functions – Retained basis artifact and operator.
area_grid – Grid-cell areas on the operator grid.
grid_cell_prior_stdev – Independent grid-cell scale-factor standard deviation.
flux – Optional replacement flux. The retained flux is used by default.

Returns:

Labelled state standard deviations named x_prior_stdev.

openghg_inversions.basis.project_native_covariance(*, covariance: InvertibleNativeCovarianceAction, basis_prolongation: DataArray, state_dim: str, native_sensitivity: DataArray, observation_dim: str, observation_covariance: Literal['dense', 'diagonal'] = 'dense', observation_batch_size: int = 64, strategy: RetainedProjectionStrategy | None = None) → NativeCovarianceProducts#

Compute coherent labelled native-covariance products eagerly.

Parameters:

covariance – Labelled native covariance action with a compatible solve.
basis_prolongation – Canonical labelled U from the basis-side native expansion boundary.
state_dim – Retained-state dimension shared by U and Pi.
native_sensitivity – Canonical labelled native sensitivity H.
observation_dim – Observation dimension in H.
observation_covariance – Return dense H B H.T or its diagonal.
observation_batch_size – Positive integral number of covariance right-hand sides per eager block.
strategy – Authoritative restriction choice; defaults to the bucket-preserving restriction.

Returns:

Frozen in-memory labelled product value object. Scaling covariance, restriction, and prolongation have units "1". Products linear in H inherit its units; observation covariance uses squared H units when supplied.

The kernel trusts the covariance action’s declared real, self-adjoint, positive-definite semantics. It does not globally certify a matrix-free B or revalidate products constructed here.

Raises:

ValueError – If labelled inputs cannot be exactly aligned, the batch size is not positive, or a required Cholesky factorization fails.

openghg_inversions.basis.quadtree_basis_from_weights(weights: DataArray, start_date: str, domain: str, *, nbasis: int = 100, seed: int | None = None) → DataArray#

Create a quadtree basis field from precomputed 2D weights.

Parameters:

weights – Two-dimensional basis weight field.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
nbasis – Desired number of basis regions.
seed – Optional seed passed to scipy.optimize.dual_annealing.

Returns:

Basis field with lat/lon dimensions, a singleton time dimension, and integer region labels.

openghg_inversions.basis.quadtree_basis_function(fp_all: dict, start_date: str, domain: str, emissions_name: list[str] | None = None, nbasis: int = 100, country_directory: str | None = None, abs_flux: bool = False, seed: int | None = None, mask: DataArray | None = None) → DataArray#

Create a basis field with the quadtree algorithm.

The domain is split with smaller grid cells for regions which contribute more to the a priori above-baseline mole fraction. This is based on the average footprint over the inversion period and the a priori emissions field.

The number of basis functions is optimised using dual annealing. Probably not the best or fastest method as there should only be one minimum, but it does not require the Jacobian or Hessian for optimisation.

Parameters:

fp_all – Legacy merged-data dictionary produced by the data preparation path.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Desired number of basis regions.
country_directory – Accepted for a consistent basis-algorithm interface; the quadtree algorithm does not use it.
abs_flux – If true, use absolute flux values when constructing weights.
seed – Optional seed passed to scipy.optimize.dual_annealing.
mask – Optional Boolean spatial mask for fitting basis functions over a sub-region.

Returns:

Basis field with lat/lon dimensions, a singleton time dimension, and integer region labels.

openghg_inversions.basis.quadtreebasisfunction(*args, **kwargs) → DataArray#: Deprecated alias for quadtree_basis_function().

openghg_inversions.basis.region_constrained_basis_from_weights(weights: DataArray, start_date: str, domain: str, *, region_classes: DataArray, nbasis: int | Mapping[Hashable, int] = 100, allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_strategy: SplitStrategy | None = None, split_acceptance: Literal['none', 'contrast_score'] = 'none', contrast_contribution: DataArray | None = None, contrast_cell_weight: DataArray | None = None, min_contrast_delta_eig: float | None = None, min_contrast_lambda: float | None = None, contrast_tau: float | None = None, contrast_sigma_design: float | None = None, contrast_s_diag: DataArray | None = None) → DataArray#

Create constrained basis labels from weights and region classes.

This is the weight-first adapter for the current region_constrained basis algorithm. Labels are generated independently within each non-null region class.

Parameters:

weights – Two-dimensional basis weight field.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
region_classes – Two-dimensional class field on the same spatial grid as weights. A full-domain field may be supplied when weights are a rectangular crop of that grid.
nbasis – Total number of basis regions, or class-local allocation accepted by region_constrained_basis.
allocation – Automatic allocation mode used when nbasis is an integer. "weight" allocates by class total weight; "area" allocates by mapped cell count.
min_regions_per_class – Minimum automatic allocation for each non-empty mapped class.
split_strategy – Optional class-local label generator. When omitted, the default greedy generator is used, optionally configured by split_acceptance.
split_acceptance – Optional split-acceptance criterion. The default "none" preserves existing behavior. "contrast_score" uses a mass-preserving observation-space contrast gate.
contrast_contribution – Design contribution array for contrast scoring.
contrast_cell_weight – Optional prior flux or split-mass field used as mu in contrast scoring. When omitted, the unnormalised input weights are used as a split-mass proxy.
min_contrast_delta_eig – Optional minimum delta_eig threshold.
min_contrast_lambda – Optional minimum lambda threshold.
contrast_tau – Prior standard deviation of the split contrast coefficient delta = alpha_A - alpha_B.
contrast_sigma_design – Optional scalar design standard deviation, equivalent to S = contrast_sigma_design**2 I.
contrast_s_diag – Optional diagonal design covariance entries in the same row space as contrast_contribution.

Returns:

Basis field with globally unique integer labels that do not cross region_classes values.

Raises:

ValueError – If both split_strategy and a non-default split_acceptance are supplied.

openghg_inversions.basis.region_constrained_basis_function(fp_all: dict, start_date: str, domain: str, emissions_name: list[str] | None = None, nbasis: int | Mapping[Hashable, int] = 100, country_directory: str | None = None, abs_flux: bool = False, mask: DataArray | None = None, region_classes: DataArray | None = None, allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_acceptance: Literal['none', 'contrast_score'] = 'none', contrast_contribution: DataArray | None = None, contrast_cell_weight: DataArray | None = None, min_contrast_delta_eig: float | None = None, min_contrast_lambda: float | None = None, contrast_tau: float | None = None, contrast_sigma_design: float | None = None, contrast_s_diag: DataArray | None = None) → DataArray#

Create weighted basis regions constrained by caller-supplied classes.

This adapter keeps file loading outside the constrained algorithm: callers provide region_classes directly, for example from a country file, land/sea file, or a user-defined region-class field. It links the pure region_constrained_basis helper to the current fp_all-based wrapper interface by constructing the usual footprint-times-flux weight field first.

Parameters:

fp_all – Legacy merged-data dictionary produced by the data preparation path.
start_date – Start date of the inversion period.
domain – Domain across which to calculate basis functions.
emissions_name – Optional list of OpenGHG flux source names used to select emissions from fp_all.
nbasis – Total number of basis regions, or class-local allocation accepted by region_constrained_basis.
country_directory – Accepted for a consistent basis-algorithm interface; file loading for region_classes must happen before calling this adapter.
abs_flux – If true, use absolute flux values when constructing weights.
mask – Optional Boolean spatial mask for fitting basis functions over a sub-region.
region_classes – Two-dimensional class field on the same spatial grid as the generated weights. Positive basis labels are generated independently within each non-null class value.
allocation – Automatic allocation mode used when nbasis is an integer. "weight" allocates regions by total class weight; "area" allocates by mapped cell count.
min_regions_per_class – Minimum automatic allocation for each non-empty mapped class.
split_acceptance – Optional split-acceptance criterion. The default "none" preserves existing behavior. "contrast_score" uses a mass-preserving observation-space contrast gate.
contrast_contribution – Design contribution array for contrast scoring, with at least one design-observation dimension plus the two spatial dimensions. Observed mole-fraction values must not be used here.
contrast_cell_weight – Optional prior flux or split-mass field used as mu in contrast scoring. When omitted, the unnormalised generated basis weight field is used as a split-mass proxy.
min_contrast_delta_eig – Optional minimum delta_eig threshold. If both contrast thresholds are omitted, contrast diagnostics are computed but proposed splits are not rejected.
min_contrast_lambda – Optional minimum lambda threshold.
contrast_tau – Prior standard deviation of the split contrast coefficient delta = alpha_A - alpha_B. If omitted, tau=1 is used and scores are uncalibrated.
contrast_sigma_design – Optional scalar design standard deviation, equivalent to S = contrast_sigma_design**2 I.
contrast_s_diag – Optional diagonal design covariance entries in the same row space as contrast_contribution.

Returns:

Basis field with lat/lon dimensions, a singleton time dimension, and globally unique integer labels that do not cross region_classes values.

Raises:

ValueError – If region_classes is not supplied.

openghg_inversions.basis.region_constrained_fixed_outer_basis_from_weights(weights: DataArray, start_date: str, domain: str, *, nbasis: int | integer = 100, outer_regions: DataArray | None = None, region_classes: DataArray | None = None, country_directory: str | Path | None = None, outer_regions_path: str | Path | None = None, allocation: Literal['weight', 'area'] = 'weight', min_regions_per_class: int = 1, split_strategy: SplitStrategy | None = None) → DataArray#

Create a constrained fixed-outer basis from precomputed weights.

The largest value in the InTEM outer-region map selects the bounded inner domain. nbasis is distributed only among the inner region_classes; each distinct non-null outer-region value outside that maximum-valued inner domain receives one fixed basis label. Inner and outer class values are tagged before constrained splitting, so their final positive integer labels are globally disjoint.

Parameters:

weights – Non-negative, two-dimensional whole-domain basis weight field whose grid defines the output coordinates. Non-finite cells are replaced by zero, but at least one finite cell is required. Unlike region_constrained_basis_from_weights(), this fixed-outer adapter does not accept cropped weights because it emits the outer states as well as the bounded inner states.
start_date – Start date of the inversion period.
domain – Domain used for output metadata and default file loading.
nbasis – Total number of requested inner-region basis labels.
outer_regions – Optional already-loaded InTEM outer-region map. When omitted, load_intem_outer_regions() is used. Supplying this field takes precedence over outer_regions_path.
region_classes – Optional already-loaded inner classification, such as a binary land/sea or multi-country integer map. Each distinct non-null selected value is a class. When omitted, load_country_region_classes() is used.
country_directory – Optional directory containing the country or land/sea class-map file. Used only when region_classes is omitted.
outer_regions_path – Optional direct path to an outer-region NetCDF file. Used only when outer_regions is omitted. When both are omitted, the packaged file for domain is used.
allocation – Mode used to distribute nbasis across selected inner classes.
min_regions_per_class – Minimum automatic allocation for each non-empty selected inner class.
split_strategy – Optional class-local label generator applied only to bounded inner classes after layout composition. Outer IDs remain fixed maps even when they are disconnected. The inner default is GreedySplitStrategy configured with AxisParallelSplitStep.

Returns:

Basis field on the weights grid with a singleton time dimension, standard generated-basis metadata, one target per non-null outer class, outside the maximum-valued inner domain, and nbasis targets allocated across the inner classes. Null outer cells remain label 0.

Raises:

TypeError – If nbasis is not a non-Boolean integral value.
ValueError – If weights, dimensions, dimension names, outer-map values, inner classes, allocation, or split-strategy labels are invalid.
FileNotFoundError – If a required default or caller-selected map file is missing.
KeyError – If a selected outer map lacks region or a selected class map lacks country.
xarray.AlignmentError – If the supplied or loaded fields are not on physically compatible spatial grids.

openghg_inversions.basis.algorithms