lair.inversion.core#

Core inversion classes and functions.

This module provides core classes and utilities for formulating and solving inverse problems, including:

Abstract base classes for inversion estimators.
Registry for estimator implementations.
Forward operator and covariance matrix wrappers with index-aware functionality.
Utilities for convolving state vectors with forward operators.
The InverseProblem class, which orchestrates the alignment of data, prior information, error covariances, and the solution process.

Functions

convolve(forward_operator, state[, ...])

Convolve a forward_operator with a state field to get modeled observations.

Classes

`CovarianceMatrix`(data)	Covariance matrix class wrapping pandas DataFrames.
`Estimator`(z, x_0, H, S_0, S_z[, c])	Base inversion estimator class.
`EstimatorRegistry`	Registry for estimator classes.
`ForwardOperator`(data)	Forward operator class for modeling observations.
`InverseProblem`(estimator, obs, prior, ...[, ...])	Inverse problem class for estimating model states from observations.
`SymmetricMatrix`(data)	Symmetric matrix wrapper class for pandas DataFrames.

class lair.inversion.core.Estimator(z: ndarray, x_0: ndarray, H: ndarray, S_0: ndarray, S_z: ndarray, c: ndarray | float | None = None)[source]#

Base inversion estimator class.

Attributes

`x_hat`	Posterior mean model state estimate (solution).
`S_hat`	Posterior error covariance matrix.

z	(np.ndarray) Observed data.
x_0	(np.ndarray) Prior model state estimate.
H	(np.ndarray) Forward operator.
S_0	(np.ndarray) Prior error covariance.
S_z	(np.ndarray) Model-data mismatch covariance.
c	(np.ndarray or float, optional) Constant data, defaults to 0.0.
n_z	(int) Number of observations.
n_x	(int) Number of state variables.
y_hat	(np.ndarray) Posterior modeled observations.
y_0	(np.ndarray) Prior modeled observations.
K	(np.ndarray) Kalman gain.
A	(np.ndarray) Averaging kernel.
chi2	(float) Chi-squared statistic.
R2	(float) Coefficient of determination.
RMSE	(float) Root mean square error.
U_red	(np.ndarray) Reduced uncertainty.

Methods

cost(x: np.ndarray) -> float	Cost/loss/misfit function.
forward(x: np.ndarray) -> np.ndarray	Forward model calculation.
residual(x: np.ndarray) -> np.ndarray	Forward model residual.
leverage(x: np.ndarray) -> np.ndarray	Calculate the leverage matrix.

__init__(z: ndarray, x_0: ndarray, H: ndarray, S_0: ndarray, S_z: ndarray, c: ndarray | float | None = None)[source]#

Initialize the Estimator object.

Parameters:

znp.ndarray: Observed data.
x_0np.ndarray: Prior model state estimate.
Hnp.ndarray: Forward operator.
S_0np.ndarray: Prior error covariance.
S_znp.ndarray: Model-data mismatch covariance.
cnp.ndarray or float, optional: Constant data, defaults to 0.0.

forward(x) → ndarray[source]#

Forward model calculation.

\[y = Hx + c\]

Parameters:

xnp.ndarray: State vector.

Returns:

np.ndarray: Model output (Hx + c).

residual(x) → ndarray[source]#

Forward model residual.

\[r = z - (Hx + c)\]

Parameters:

xnp.ndarray: State vector.

Returns:

np.ndarray: Residual (z - (Hx + c)).

leverage(x) → ndarray[source]#

Calculate the leverage matrix.

Which observations are likely to have more impact on the solution.

\[L = Hx ((Hx)^T (H S_0 H^T + S_z)^{-1} Hx)^{-1} (Hx)^T (H S_0 H^T + S_z)^{-1}\]

Parameters:

xnp.ndarray: State vector.

Returns:

np.ndarray: Leverage matrix.

abstract cost(x) → float[source]#

Cost/loss/misfit function.

Parameters:

xnp.ndarray: State vector.

Returns:

float: Cost value.

abstract property x_hat: ndarray#

Posterior mean model state estimate (solution).

Returns:

np.ndarray: Posterior state estimate.

abstract property S_hat: ndarray#

Posterior error covariance matrix.

Returns:

np.ndarray: Posterior error covariance matrix.

property y_hat: ndarray#

Posterior mean observation estimate.

\[\hat{y} = H \hat{x} + c\]

Returns:

np.ndarray: Posterior observation estimate.

property y_0: ndarray#

Prior mean data estimate.

\[\hat{y}_0 = H x_0 + c\]

Returns:

np.ndarray: Prior data estimate.

property K#

Kalman gain matrix.

\[K = (H S_0)^T (H S_0 H^T + S_z)^{-1}\]

Returns:

np.ndarray: Kalman gain matrix.

property A#

Averaging kernel matrix.

\[A = KH = (H S_0)^T (H S_0 H^T + S_z)^{-1} H\]

Returns:

np.ndarray: Averaging kernel matrix.

property DOFS: float#

Degrees Of Freedom for Signal (DOFS).

\[DOFS = Tr(A)\]

Returns:

float: Degrees of Freedom value.

property chi2: float#

Reduced Chi-squared statistic.

\[\chi^2 = \frac{1}{n_z} ((z - H\hat{x})^T S_z^{-1} (z - H\hat{x}) + (\hat{x} - x_0)^T S_0^{-1} (\hat{x} - x_0))\]

Returns:

float: Reduced Chi-squared value.

property chi2_obs: float#

Chi-squared statistic for observation params

\[\chi^2 = (z - H\hat{x})^T S_z^{-1} (z - H\hat{x})\]

Returns:

float: Chi-squared value.

property chi2_state: float#: Chi-squared statistic for state params

\[\chi^2 = (\hat{x} - x_0)^T S_0^{-1} (\hat{x} - x_0)\]

property R2: float#

Coefficient of determination (R-squared).

\[R^2 = corr(z, H\hat{x})^2\]

Returns:

float: R-squared value.

property RMSE: float#

Root mean square error (RMSE).

\[RMSE = \sqrt{\frac{(z - H\hat{x})^2}{n_z}}\]

Returns#

float: RMSE value.

property U_red#

Uncertainty reduction metric.

\[U_{red} = 1 - \frac{\sqrt{trace(\hat{S})}}{\sqrt{trace(S_0)}}\]

Returns:

float: Uncertainty reduction value.

class lair.inversion.core.EstimatorRegistry[source]#

Registry for estimator classes.

register(name: str)[source]#

Register an estimator class under a given name.

Parameters:

namestr: Name to register the estimator under.

Returns:

decoratorfunction: Decorator to register the class.

lair.inversion.core.convolve(forward_operator: DataFrame, state: Series, coord_decimals: int = 6) → Series[source]#

Convolve a forward_operator with a state field to get modeled observations.

Parameters:

forward_operatorpd.DataFrame: DataFrame with columns corresponding to the state index and rows corresponding to the observation index.
statepd.Series: Series with rows corresponding to the state index.
coord_decimalsint, optional: Number of decimal places to round coordinates to when matching indices, by default 6.

Returns:

pd.Series: Series with the same index as the forward_operator, containing the modeled observations.

class lair.inversion.core.ForwardOperator(data: DataFrame)[source]#

Forward operator class for modeling observations.

Parameters:

datapd.DataFrame: Forward operator matrix.

Attributes

`data`	Get the underlying data of the forward operator.
`obs_index`	Get the observation index (row index) of the forward operator.
`state_index`	Get the state index (column index) of the forward operator.
`obs_dims`	Get the observation dimensions (names of the row index).
`state_dims`	Get the state dimensions (names of the column index).

Methods

convolve(state: pd.Series, coord_decimals: int = 6) -> pd.Series	Convolve the forward operator with a state vector.
to_xarray() -> xr.DataArray	Convert the forward operator to an xarray DataArray.

__init__(data: DataFrame)[source]#

Initialize the ForwardOperator.

Parameters:

datapd.DataFrame: Forward operator matrix.

property data: DataFrame#

Get the underlying data of the forward operator.

Returns:

pd.DataFrame: Forward operator matrix.

property obs_index: Index#

Get the observation index (row index) of the forward operator.

Returns:

pd.Index: Observation index.

property state_index: Index#

Get the state index (column index) of the forward operator.

Returns:

pd.Index: State index.

property obs_dims: tuple#

Get the observation dimensions (names of the row index).

Returns:

tuple: Observation dimension names.

property state_dims: tuple#

Get the state dimensions (names of the column index).

Returns:

tuple: State dimension names.

convolve(state: Series, coord_decimals: int = 6) → Series[source]#

Convolve the forward operator with a state vector.

Parameters:

statepd.Series: State vector.
coord_decimalsint, optional: Number of decimal places to round coordinates to when matching indices, by default 6.

Returns:

pd.Series: Result of convolution.

to_xarray() → DataArray[source]#

Convert the forward operator to an xarray DataArray.

Returns:

xr.DataArray: Xarray representation of the forward operator.

class lair.inversion.core.SymmetricMatrix(data: DataFrame)[source]#

Symmetric matrix wrapper class for pandas DataFrames.

Parameters:

datapd.DataFrame: Symmetric matrix with identical row and column indices.

Attributes

`data`	Returns the underlying data as a pandas DataFrame.
`index`	Returns the pandas Index of the matrix.
`dims`	Returns a tuple representing the dimension names of the matrix.
`values`	Returns the underlying data as a NumPy array.
`shape`	Returns a tuple representing the dimensionality of the matrix.

loc

(SymmetricMatrix._Indexer) Custom accessor for label-based selection and assignment.

Methods

from_numpy(array: np.ndarray, index: pd.Index) -> SymmetricMatrix	Create a SymmetricMatrix from a NumPy array and an index.
reindex(index: pd.Index, kwargs) -> SymmetricMatrix**	Reindex the symmetric matrix, filling new entries with 0.
reorder_levels(order) -> SymmetricMatrix	Reorder the levels of a MultiIndex symmetric matrix.

__init__(data: DataFrame)[source]#

Initialize the SymmetricMatrix with a square DataFrame.

Parameters:

datapd.DataFrame: Square symmetric matrix.

classmethod from_numpy(array: ndarray, index: Index) → Self[source]#

Create a SymmetricMatrix from a NumPy array.

Parameters:

arraynp.ndarray: Symmetric matrix array.
indexpd.Index: Index for rows and columns.

Returns:

SymmetricMatrix: SymmetricMatrix instance.

property data: DataFrame#

Returns the underlying data as a pandas DataFrame.

Returns:

pd.DataFrame: Underlying symmetric matrix.

property dims: tuple#

Returns a tuple representing the dimension names of the matrix.

Returns:

tuple: Dimension names of the symmetric matrix.

property index: Index#

Returns the pandas Index of the matrix.

Returns:

pd.Index: Index of the symmetric matrix.

property values: ndarray#

Returns the underlying data as a NumPy array.

Returns:

np.ndarray: Underlying data array.

property shape: tuple#

Returns a tuple representing the dimensionality of the matrix.

Returns:

tuple: Dimensionality of the symmetric matrix.

reindex(index: Index, **kwargs) → SymmetricMatrix[source]#

Reindex the symmetric matrix, filling new entries with 0.

Parameters:

indexpd.Index: New index for the symmetric matrix.
**kwargsadditional keyword arguments: Passed to pandas’ reindex method.

Returns:

SymmetricMatrix: Reindexed SymmetricMatrix instance.

reorder_levels(order) → SymmetricMatrix[source]#

Reorder the levels of a MultiIndex symmetric matrix.

Parameters:

orderlist: New order for the levels.

Returns:

SymmetricMatrix: SymmetricMatrix instance with reordered levels.

Raises:

TypeError: If the index is not a MultiIndex.

class lair.inversion.core.CovarianceMatrix(data: DataFrame)[source]#

Covariance matrix class wrapping pandas DataFrames.

Attributes

variance

Returns the diagonal of the covariance matrix (the variances).

property variance: Series#

Returns the diagonal of the covariance matrix (the variances).

Returns:

pd.Series: Series containing the variances.

class lair.inversion.core.InverseProblem(estimator: str | type[Estimator], obs: Series, prior: Series, forward_operator: ForwardOperator | DataFrame, prior_error: SymmetricMatrix, modeldata_mismatch: SymmetricMatrix, constant: float | Series | None = None, state_index: Index | None = None, estimator_kwargs: dict = {}, coord_decimals: int = 6)[source]#

Inverse problem class for estimating model states from observations.

Represents a statistical inverse problem for estimating model states from observed data using Bayesian inference and linear forward operators.

An inverse problem seeks to infer unknown model parameters (the “state”) from observed data, given prior knowledge and a mathematical relationship (the forward operator) that links the state to the observations. This class provides a flexible interface for formulating and solving such problems using various estimators.

Parameters:

estimatorstr or type[Estimator]: The estimator to use for solving the inverse problem. Can be the name of a registered estimator or an Estimator class.
obspd.Series: Observed data as a pandas Series, indexed by observation dimensions.
priorpd.Series: Prior estimate of the model state as a pandas Series, indexed by state dimensions.
forward_operatorForwardOperator or pd.DataFrame: Linear operator mapping model state to observations. Can be a ForwardOperator instance or a pandas DataFrame with appropriate indices and columns.
prior_errorCovarianceMatrix: Covariance matrix representing uncertainty in the prior state estimate.
modeldata_mismatchCovarianceMatrix: Covariance matrix representing uncertainty in the observed data (model-data mismatch).
constantfloat or pd.Series or None, optional: Optional constant term added to the forward model output. If not provided, defaults to zero.
state_indexpd.Index or None, optional: Index for the state variables. If None, uses the index from the prior.
estimator_kwargsdict, optional: Additional keyword arguments to pass to the estimator.
coord_decimalsint, optional: Number of decimal places to round coordinate values for alignment (default is 6).

Attributes

`n_obs`	Number of observations.
`n_state`	Number of state variables.

obs_index	(pd.Index) Index of the observations used in the problem.
state_index	(pd.Index) Index of the state variables used in the problem.
obs_dims	(tuple) Names of the observation dimensions.
state_dims	(tuple) Names of the state dimensions.
posterior	(pd.Series) Posterior mean estimate of the model state.
posterior_error	(CovarianceMatrix) Posterior error covariance matrix.
posterior_obs	(pd.Series) Posterior mean estimate of the observations.
prior_obs	(pd.Series) Prior mean estimate of the observations.
xr	(InverseProblem._XR) Xarray interface for accessing inversion results as xarray DataArrays.

Methods

solve() -> dict[str, pd.Series | CovarianceMatrix | pd.Series]

Solves the inverse problem and returns a dictionary with posterior state, posterior error covariance, and posterior observation estimates.

Raises:

TypeError: If input types are incorrect.
ValueError: If input data dimensions are incompatible or indices do not align.

Notes

This class is designed for linear inverse problems with Gaussian error models, commonly encountered in geosciences, remote sensing, and other fields where model parameters are inferred from indirect measurements. It supports flexible input formats and provides robust alignment and validation of input data.

__init__(estimator: str | type[Estimator], obs: Series, prior: Series, forward_operator: ForwardOperator | DataFrame, prior_error: SymmetricMatrix, modeldata_mismatch: SymmetricMatrix, constant: float | Series | None = None, state_index: Index | None = None, estimator_kwargs: dict = {}, coord_decimals: int = 6) → None[source]#

Initialize the InverseProblem.

Parameters:

estimatorstr or type[Estimator]: Estimator class or its name as a string.
obspd.Series: Observed data.
priorpd.Series: Prior model state estimate.
forward_operatorpd.DataFrame: Forward operator matrix.
prior_errorCovarianceMatrix: Prior error covariance matrix.
modeldata_mismatchCovarianceMatrix: Model-data mismatch covariance matrix.
constantfloat or pd.Series, optional: Constant data, defaults to 0.0.
state_indexpd.Index, optional: Index for the state variables.
estimator_kwargsdict, optional: Additional keyword arguments for the estimator.
obs_aggregationoptional: Observation aggregation method.
coord_decimalsint, optional: Number of decimal places for rounding coordinates.

Raises:

TypeError: If any of the inputs are of the wrong type.
ValueError: If there are issues with the input data (e.g., incompatible dimensions).

solve() → dict[str, Series | SymmetricMatrix][source]#

Solve the inversion problem using the configured estimator.

Returns:

dict[str, State | Covariance | Data]: A dictionary containing the posterior estimates: - ‘posterior’: Pandas series with the posterior mean model estimate. - ‘posterior_error’: Covariance object with the posterior error covariance matrix. - ‘posterior_obs’: Pandas series with the posterior observation estimates.

property n_obs: int#

Number of observations.

Returns:

int: Number of observations.

property n_state: int#

Number of state variables.

Returns:

int: Number of state variables.

property posterior: Series#

Posterior state estimate.

Returns:

pd.Series: Pandas series with the posterior mean model estimate.

property posterior_obs: Series#

Posterior observation estimates.

Returns:

pd.Series: Pandas series with the posterior observation estimates.

property posterior_error: SymmetricMatrix#

Posterior error covariance matrix.

Returns:

CovarianceMatrix: CovarianceMatrix instance with the posterior error covariance matrix.

property prior_obs: Series#

Prior observation estimates.

Returns:

pd.Series: Pandas series with the prior observation estimates.