fips

fips

Flexible Inverse Problem Solver (FIPS)

class fips.Estimator(z, x_0, H, S_0, S_z, c=None)

Base inversion estimator class.

z

Observed data.

Type:

np.ndarray

x_0

Prior model state estimate.

Type:

np.ndarray

H

Forward operator.

Type:

np.ndarray

S_0

Prior error covariance.

Type:

np.ndarray

S_z

Model-data mismatch covariance.

Type:

np.ndarray

c

Constant data, defaults to 0.0.

Type:

np.ndarray or float, optional

n_z

Number of observations.

Type:

int

n_x

Number of state variables.

Type:

int

x_hat

Posterior mean model state estimate (solution).

Type:

np.ndarray

S_hat

Posterior error covariance.

Type:

np.ndarray

y_hat

Posterior modeled observations.

Type:

np.ndarray

y_0

Prior modeled observations.

Type:

np.ndarray

K

Kalman gain.

Type:

np.ndarray

A

Averaging kernel.

Type:

np.ndarray

chi2

Chi-squared statistic.

Type:

float

R2

Coefficient of determination.

Type:

float

RMSE

Root mean square error.

Type:

float

U_red

Reduced uncertainty.

Type:

np.ndarray

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, x_0, H, S_0, S_z, c=None)

Initialize the Estimator object.

Parameters:

• 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.

forward(x)

Forward model calculation.

\[y = Hx + c\]

Parameters:

x (np.ndarray) – State vector.

Returns:

Model output (Hx + c).

Return type:

np.ndarray

residual(x)

Forward model residual.

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

Parameters:

x (np.ndarray) – State vector.

Returns:

Residual (z - (Hx + c)).

Return type:

np.ndarray

leverage(x)

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:

x (np.ndarray) – State vector.

Returns:

Leverage matrix.

Return type:

np.ndarray

abstract cost(x)

Cost/loss/misfit function.

Parameters:

x (np.ndarray) – State vector.

Returns:

Cost value.

Return type:

float

abstract property x_hat: ndarray

Posterior mean model state estimate (solution).

Returns:

Posterior state estimate.

Return type:

np.ndarray

abstract property S_hat: ndarray

Posterior error covariance matrix.

Returns:

Posterior error covariance matrix.

Return type:

np.ndarray

property y_hat: ndarray

Posterior mean observation estimate.

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

Returns:

Posterior observation estimate.

Return type:

np.ndarray

property y_0: ndarray

Prior mean data estimate.

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

Returns:

Prior data estimate.

Return type:

np.ndarray

property K

Kalman gain matrix.

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

Returns:

Kalman gain matrix.

Return type:

np.ndarray

property A

Averaging kernel matrix.

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

Returns:

Averaging kernel matrix.

Return type:

np.ndarray

property DOFS: float

Degrees Of Freedom for Signal (DOFS).

\[DOFS = Tr(A)\]

Returns:

Degrees of Freedom value.

Return type:

float

property reduced_chi2: float

Reduced Chi-squared statistic. Tarantola (1987)

\[\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))\]

Note

I can’t find a copy of Tarantola (1987) to verify this equation, but it appears in Kunik et al. (2019) https://doi.org/10.1525/elementa.375

Returns:

Reduced Chi-squared value.

Return type:

float

property R2: float

Coefficient of determination (R-squared).

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

Returns:

R-squared value.

Return type:

float

property RMSE: float

Root mean square error (RMSE).

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

Returns:

RMSE value.

Return type:

float

property U_red

Uncertainty reduction metric.

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

Returns:

Uncertainty reduction value.

Return type:

float

class fips.ForwardOperator(data)

Forward operator class for modeling observations.

Parameters:

data (pd.DataFrame) – Forward operator matrix.

data

Underlying forward operator matrix.

Type:

pd.DataFrame

obs_index

Observation index (row index).

Type:

pd.Index

state_index

State index (column index).

Type:

pd.Index

obs_dims

Observation dimension names.

Type:

tuple

state_dims

State dimension names.

Type:

tuple

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)

Initialize the ForwardOperator.

Parameters:

data (pd.DataFrame) – Forward operator matrix.

property data: DataFrame

Get the underlying data of the forward operator.

Returns:

Forward operator matrix.

Return type:

pd.DataFrame

property obs_index: Index

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

Returns:

Observation index.

Return type:

pd.Index

property state_index: Index

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

Returns:

State index.

Return type:

pd.Index

property obs_dims: tuple

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

Returns:

Observation dimension names.

Return type:

tuple

property state_dims: tuple

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

Returns:

State dimension names.

Return type:

tuple

convolve(state, coord_decimals=6)

Convolve the forward operator with a state vector.

Parameters:

• state (pd.Series) – State vector.

• coord_decimals (int, optional) – Number of decimal places to round coordinates to when matching indices, by default 6.

Returns:

Result of convolution.

Return type:

pd.Series

to_xarray()

Convert the forward operator to an xarray DataArray.

Returns:

Xarray representation of the forward operator.

Return type:

xr.DataArray

class fips.CovarianceMatrix(data)

Covariance matrix class wrapping pandas DataFrames.

variance

Series containing the variances (diagonal elements).

Type:

pd.Series

property variances: Series

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

Returns:

Series containing the variances.

Return type:

pd.Series

classmethod from_variances(variances, index=None, **kwargs)

Return type:

Self

class fips.InverseProblem(estimator, obs, prior, forward_operator, prior_error, modeldata_mismatch, constant=None, state_index=None, estimator_kwargs=None, coord_decimals=6)

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:

• estimator (str or type[Estimator]) – The estimator to use for solving the inverse problem. Can be the name of a registered estimator or an Estimator class.

• obs (pd.Series) – Observed data as a pandas Series, indexed by observation dimensions.

• prior (pd.Series) – Prior estimate of the model state as a pandas Series, indexed by state dimensions.

• forward_operator (ForwardOperator 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_error (CovarianceMatrix) – Covariance matrix representing uncertainty in the prior state estimate.

• modeldata_mismatch (CovarianceMatrix) – Covariance matrix representing uncertainty in the observed data (model-data mismatch).

• constant (float or pd.Series or None, optional) – Optional constant term added to the forward model output. If not provided, defaults to zero.

• state_index (pd.Index or None, optional) – Index for the state variables. If None, uses the index from the prior.

• estimator_kwargs (dict, optional) – Additional keyword arguments to pass to the estimator.

• coord_decimals (int, optional) – Number of decimal places to round coordinate values for alignment (default is 6).

Raises:

• TypeError – If input types are incorrect.

• ValueError – If input data dimensions are incompatible or indices do not align.

obs_index

Index of the observations used in the problem.

Type:

pd.Index

state_index

Index of the state variables used in the problem.

Type:

pd.Index

obs_dims

Names of the observation dimensions.

Type:

tuple

state_dims

Names of the state dimensions.

Type:

tuple

n_obs

Number of observations.

Type:

int

n_state

Number of state variables.

Type:

int

posterior

Posterior mean estimate of the model state.

Type:

pd.Series

posterior_error

Posterior error covariance matrix.

Type:

CovarianceMatrix

posterior_obs

Posterior mean estimate of the observations.

Type:

pd.Series

prior_obs

Prior mean estimate of the observations.

Type:

pd.Series

xr

Xarray interface for accessing inversion results as xarray DataArrays.

Type:

InverseProblem._XR

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.

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, obs, prior, forward_operator, prior_error, modeldata_mismatch, constant=None, state_index=None, estimator_kwargs=None, coord_decimals=6)

Initialize the InverseProblem.

Parameters:

• estimator (str or type[Estimator]) – Estimator class or its name as a string.

• obs (pd.Series) – Observed data.

• prior (pd.Series) – Prior model state estimate.

• forward_operator (pd.DataFrame) – Forward operator matrix.

• prior_error (CovarianceMatrix) – Prior error covariance matrix.

• modeldata_mismatch (CovarianceMatrix) – Model-data mismatch covariance matrix.

• constant (float or pd.Series, optional) – Constant data, defaults to 0.0.

• state_index (pd.Index, optional) – Index for the state variables.

• estimator_kwargs (dict, optional) – Additional keyword arguments for the estimator.

• obs_aggregation (optional) – Observation aggregation method.

• coord_decimals (int, 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()

Solve the inversion problem using the configured estimator.

Returns:

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.

Return type:

dict[str, State | Covariance | Data]

property n_obs: int

Number of observations.

Returns:

Number of observations.

Return type:

int

property n_state: int

Number of state variables.

Returns:

Number of state variables.

Return type:

int

property posterior: Series

Posterior state estimate.

Returns:

Pandas series with the posterior mean model estimate.

Return type:

pd.Series

property posterior_obs: Series

Posterior observation estimates.

Returns:

Pandas series with the posterior observation estimates.

Return type:

pd.Series

property posterior_error: SymmetricMatrix

Posterior error covariance matrix.

Returns:

CovarianceMatrix instance with the posterior error covariance matrix.

Return type:

CovarianceMatrix

property prior_obs: Series

Prior observation estimates.

Returns:

Pandas series with the prior observation estimates.

Return type:

pd.Series

fips.convolve(forward_operator, state, coord_decimals=6)

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

Parameters:

• forward_operator (pd.DataFrame) – DataFrame with columns corresponding to the state index and rows corresponding to the observation index.

• state (pd.Series) – Series with rows corresponding to the state index.

• coord_decimals (int, optional) – Number of decimal places to round coordinates to when matching indices, by default 6.

Returns:

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

Return type:

pd.Series

Modules

estimators	Inversion estimators.
matrices
operator
problem	Core inversion classes and functions.
problems
utils	Utility functions for inversion module.