openghg_inversions.basis.prior_uncertainty#

Basis-aware projection and calibration of scale-factor prior uncertainty.

The public helpers in this module operate on retained BasisFunctions objects. They treat grid-cell scale perturbations as independent and project their standard deviations onto the operator’s labelled state coordinate.

openghg_inversions.basis.prior_uncertainty.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.prior_uncertainty.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.