openghg_inversions.models.state_activity#

Label-aware active/fixed state-vector policies for linear inversion models.

This module separates state selection from PyMC graph construction. A StateActivity policy can combine exact-zero sensitivity pruning with an explicit labelled activity mask and fixed basis_group labels. Detection follows the state coordinate order on the supplied sensitivity matrix, and resolution follows the resulting labelled mask; integer label ranges are never inferred.

Inactive states remain part of the public state vector and use labelled or scalar fixed values. The default fixed value is one, which preserves the prior forward-model contribution of a multiplicative flux-scaling state.

prepare_linear_sensitivity validates a sensitivity matrix, removes exact-zero columns, and retains the full-state mapping. resolve_state_activity combines that mapping with a policy to produce the canonical ResolvedStateActivity; active_prior_args then aligns and subsets state-valued prior parameters. Finite checks, exact-zero reductions, and state-vector alignment are explicit eager-compute boundaries for lazy or Dask-backed inputs during model building.

openghg_inversions.models.state_activity.ActivityValue = bool | numpy.ndarray | xarray.core.dataarray.DataArray#: Strictly boolean scalar, positional mask, or labelled mask.

openghg_inversions.models.state_activity.FixedValue = float | int | numpy.ndarray | xarray.core.dataarray.DataArray#: Numeric scalar, positional vector, or labelled vector for inactive states.

class openghg_inversions.models.state_activity.PreparedLinearSensitivity(sensitivity: DataArray, removed: DataArray, output_dim: str)#

Bases: object

A retained sensitivity matrix and its lossless full-state mapping.

output_dim: str#

removed: DataArray#

property retained_indices: ndarray#: Return full-state positions retained by sensitivity.

sensitivity: DataArray#

property state_dim: str#: Return the sole state dimension.

class openghg_inversions.models.state_activity.ResolvedStateActivity(state_dim: str, active: DataArray, fixed_value: DataArray, zero_sensitivity: DataArray)#

Bases: object

A state-activity policy aligned to one detected sensitivity matrix.

Variables:

state_dim (str) – Canonical state dimension name from the detection mask.
active (xarray.core.dataarray.DataArray) – Boolean mask in canonical state order.
fixed_value (xarray.core.dataarray.DataArray) – Fixed values in canonical state order.
zero_sensitivity (xarray.core.dataarray.DataArray) – Labelled mask identifying exactly-zero design columns and carrying the state coordinates used for graph construction.

active: DataArray#

property active_indices: ndarray#: Return positional indices of active states in canonical order.

property fixed_indices: ndarray#: Return positional indices of inactive states in canonical order.

fixed_value: DataArray#

property n_active: int#: Return the number of sampled states.

property n_state: int#: Return the full state-vector length.

state_dim: str#

zero_sensitivity: DataArray#

Bases: object

Describe which states are sampled and how inactive states are fixed.

Parameters:

active – Boolean scalar, positional one-dimensional mask in canonical state order, or labelled one-dimensional mask. A labelled mask is aligned to the canonical state coordinate carried by the zero-sensitivity mask, so its input order need not match the canonical order. Set this to False to freeze a whole component or sector.
fixed_value – Scalar or one-dimensional state-aligned values used for inactive states. Multiplicative scaling states default to one.
fixed_groups – basis_group labels to freeze. Group selection is by coordinate value, never by state-number ranges.
group_coord – Name of the state coordinate containing group labels.

Explicit active masks and fixed groups are combined with structural zero-column removal using logical AND. Structural removal is owned by sensitivity preparation and cannot be disabled as an activity policy.

active: bool | ndarray | DataArray = True#

fixed_groups: tuple[str, ...] = ()#

fixed_value: float | int | ndarray | DataArray = 1.0#

group_coord: str = 'basis_group'#

openghg_inversions.models.state_activity.active_prior_args(prior_args: dict[str, Any], activity: ResolvedStateActivity) → dict[str, Any]#

Return prior arguments sliced to active states in canonical order.

Scalar parameters are retained. One-dimensional NumPy state parameters are interpreted in canonical order and must describe the full state vector. Labelled xarray parameters are first aligned by the canonical state coordinate and then subset, allowing input label order to differ safely. Array-backed parameters are materialized at this model-building boundary. The support arrays of an Interpolated prior are preserved rather than interpreted as state-valued parameters.

Parameters:

prior_args – PyMC prior specification.
activity – Resolved activity contract in canonical state order.

Returns:

A copy of prior_args containing scalar or active-state parameters.

Raises:

ValueError – If an array-valued distribution parameter is not scalar or full-state one-dimensional data.

openghg_inversions.models.state_activity.detect_zero_sensitivity(sensitivity: DataArray, *, output_dim: str = 'nmeasure') → DataArray#

Return the labelled mask of exactly-zero sensitivity columns.

Parameters:

sensitivity – Finite two-dimensional sensitivity matrix containing output_dim and one uniquely labelled state dimension.
output_dim – Name of the observation/output dimension.

Returns:

A materialized boolean mask over the state dimension. State labels and auxiliary state coordinates are retained from sensitivity.

Raises:

ValueError – If sensitivity is not a finite two-dimensional design with the required output dimension and unique state labels.

Notes

Finite validation and exact-zero reduction materialize lazy design data during model construction.

openghg_inversions.models.state_activity.prepare_linear_sensitivity(sensitivity: DataArray, *, output_dim: str = 'nmeasure') → PreparedLinearSensitivity#

Remove exact-zero columns once and retain their full-state mapping.

This is the eager inspection boundary for a labelled sensitivity matrix. The returned sensitivity keeps borrowed array data and contains only nonzero columns; removed retains the complete scientific state coordinate and auxiliary state metadata for reconstruction and provenance.

openghg_inversions.models.state_activity.resolve_state_activity(zero_sensitivity: DataArray, policy: StateActivity | None = None) → ResolvedStateActivity#

Resolve an active/fixed policy against a labelled zero-state mask.

Parameters:

zero_sensitivity – One-dimensional, strictly boolean mask identifying exactly-zero design columns. It must have a unique labelled state coordinate and may carry auxiliary state coordinates used by the policy.
policy – Optional activity policy. When omitted, every retained column is active and structurally removed states use inactive value one.

Returns:

A policy aligned to the mask’s canonical state coordinate.

Raises:

ValueError – If the zero mask is not one-dimensional, boolean, and uniquely labelled; supplied arrays cannot be aligned; or requested group metadata is absent or not state-aligned.

Notes

Policy vectors are materialized during model construction. Use detect_zero_sensitivity to validate and reduce a sensitivity matrix before calling this function.