API Reference

Core Data Structures

Block

class fips.Block(data, name=None, index=None, dtype=None, copy=False)

Single data block with a named Series and consistent index.

A Block wraps a pandas Series and can be initialized from an existing Series or from raw values.

Blocks are the fundamental building units of fips. Inverse problems can be customized by creating Blocks with specific indices and names to represent different state or observation components relevant to the application.

name

Name of the block.

Type:

str

data

The underlying Series containing the block data.

Type:

pd.Series

index

Index for the block.

Type:

pd.Index

shape

Shape of the block (number of elements).

Type:

tuple

values

The underlying data values as a NumPy array.

Type:

np.ndarray

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index values.

reindex(new_index, fill_value=0.0)

Reindex the block to new row indices, filling missing values with fill_value.

round_index(decimals, axis=0)

Round the index and to a specified number of decimal places for alignment.

copy()

Return a copy of the Block.

to_series(add_block_level=False)

Convert to a Series, optionally adding block levels to the index.

to_xarray()

Convert the Block to an xarray DataArray.

to_numpy()

Get the underlying data as a NumPy array.

data: Series

__init__(data, name=None, index=None, dtype=None, copy=False)

Initialize a Block.

Parameters:

• data (pd.Series, Block, or array-like) – Data for the block. If Block, creates a copy.

• name (str, optional) – Name for the block. If None, uses data.name.

• index (pd.Index, optional) – Index for the block. If None, uses data.index.

• dtype (dtype, optional) – Data type to force.

• copy (bool, default False) – Whether to copy the underlying data.

__repr__()

Return string representation.

to_series(add_block_level=False)

Return the underlying Series data.

Parameters:

add_block_level (bool, default False) – Whether to add a ‘block’ level to the index with the block name.

Returns:

The underlying Series data, optionally with a ‘block’ level added to the index.

Return type:

pd.Series

to_xarray()

Convert the Block to an xarray DataArray.

Return type:

DataArray

Vector

class fips.Vector(data, name=None, index=None, dtype=None, copy=False)

State or observation vector composed of one or more Block objects.

A Vector organizes one or more Blocks (prior, posterior, observations, etc.) into a single hierarchical structure.

Vectors are used to represent the full state or observation space and are the 1D matrix components in the inversion framework.

name

Name of the Vector. Optional.

Type:

str, optional

data

The underlying Series containing the vector data.

Type:

pd.Series

index

Index for the vector.

Type:

pd.Index

shape

Shape of the vector (number of elements).

Type:

tuple

values

The underlying data values as a NumPy array.

Type:

np.ndarray

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index values.

reindex(new_index, fill_value=0.0)

Reindex the vector to new row indices, filling missing values with fill_value.

round_index(decimals, axis=0)

Round the index and to a specified number of decimal places for alignment.

copy()

Return a copy of the Vector.

to_series()

Convert to a Series.

to_xarray()

Convert the Vector to an xarray DataArray or Dataset.

to_numpy()

Get the underlying data as a NumPy array.

data: Series

__init__(data, name=None, index=None, dtype=None, copy=False)

Initialize a Vector.

Parameters:

• data (pd.Series, Vector, Block, Sequence[Block | pd.Series], or array-like) – Data for the vector.

• name (str, optional) – Name for the Vector.

• index (pd.Index, optional) – Index for the Vector. If None, uses data.index. Index must have a ‘block’ level if data is a Series.

• dtype (dtype, optional) – Data type to force.

• copy (bool, default False) – Whether to copy the underlying data.

__repr__()

Return string representation.

Return type:

str

__getitem__(block)

Get block by name.

Return type:

Series

property blocks: _BlockAccessor

Accessor for retrieving Block instances from the Vector.

to_xarray()

Convert the Vector to xarray.

If the Vector contains multiple blocks, returns an xarray Dataset with each block as a separate DataArray. If the Vector contains a single block, returns an xarray DataArray.

Return type:

DataArray | Dataset

MatrixBlock

class fips.MatrixBlock(data, row_block=None, col_block=None, name=None, index=None, columns=None, dtype=None, copy=False, sparse=False)

Single 2D data block with row and column block names.

A MatrixBlock wraps a pandas DataFrame and can be initialized from an existing DataFrame or from raw values.

MatrixBlocks are the fundamental 2D building units of fips, used to compose larger Matrix objects. MatrixBlocks represent the relationships between specific row and column blocks (e.g., state-to-observation mappings in forward operators, or covariance submatrices between specific state components). By organizing data into MatrixBlocks, users can create modular and interpretable representations of complex inverse problems, with clear semantics for how different components interact.

name

Name of the block. Defaults to “{row_block}_{col_block}” if not provided.

Type:

str

data

The underlying DataFrame containing the block’s data.

Type:

pd.DataFrame

row_block

Name of the row block (e.g., “state”, “obs”).

Type:

str

col_block

Name of the column block (e.g., “state”, “obs”).

Type:

str

index

Index for the rows of the DataFrame.

Type:

pd.Index

columns

Index for the columns of the DataFrame.

Type:

pd.Index

shape

Shape of the block (number of rows, number of columns).

Type:

tuple

values

The underlying data values, whether sparse or dense.

Type:

np.ndarray

is_sparse

Whether the block is stored in sparse format.

Type:

bool

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index/column values.

reindex(new_index, new_columns, fill_value=0.0)

Reindex the block to new row and column indices, filling missing values with fill_value.

round_index(decimals, axis='both')

Round the index and/or columns to a specified number of decimal places for alignment.

copy()

Return a copy of the MatrixBlock.

to_frame(add_block_level=False)

Convert to a DataFrame, optionally adding block levels to the index and columns.

to_dense()

Return a copy of the block with dense internal storage.

to_sparse(threshold=None)

Return a copy of the block with sparse internal storage, zeroing values below the threshold.

to_numpy()

Get the underlying data as a NumPy array.

data: DataFrame

name: str

__init__(data, row_block=None, col_block=None, name=None, index=None, columns=None, dtype=None, copy=False, sparse=False)

Initialize a MatrixBlock.

Parameters:

• data (np.ndarray or pd.DataFrame or MatrixBlock or scalar) – 2D data representing the block. If MatrixBlock, creates a copy.

• row_block (str, optional) – Name of the row block (e.g., “state”, “obs”). Required if data is not a MatrixBlock.

• col_block (str, optional) – Name of the column block (e.g., “state”, “obs”). Required if data is not a MatrixBlock.

• name (str, optional) – Name for the block. If None, defaults to “{row_block}_{col_block}”.

• index (pd.Index, optional) – Index for the rows of the DataFrame.

• columns (pd.Index, optional) – Index for the columns of the DataFrame. If None, uses the same as index.

• dtype (data type, optional) – Data type to force.

• copy (bool, optional) – Whether to copy the data.

• sparse (bool, default False) – If True, store the block in pandas sparse format. Sparsification is applied after initialization. Use threshold zeroing in your builder before passing data here for best results.

__repr__()

Return string representation.

to_frame(add_block_level=False)

Convert to DataFrame with optional block level.

Parameters:

add_block_level (bool, default False) – Whether to add ‘block’ levels to the index and columns for the row and column blocks.

Returns:

The DataFrame representation of the block, with optional block levels in the index and columns.

Return type:

pd.DataFrame

__getstate__()

Explicit pickle support: return state as dict.

__setstate__(state)

Explicit pickle support: restore state from dict.

Matrix

class fips.Matrix(data, name=None, index=None, columns=None, dtype=None, copy=None, sparse=False)

Base class for all matrix-like objects in the inversion framework.

Wraps a pandas DataFrame and ensures consistent index handling. Matrices represent 2D components of the inversion problem, such as forward operators and covariance matrices.

name

Name of the matrix. Optional.

Type:

str | None

data

The underlying DataFrame containing the matrix data.

Type:

pd.DataFrame

index

Index for the rows of the DataFrame.

Type:

pd.MultiIndex

columns

Index for the columns of the DataFrame.

Type:

pd.MultiIndex

shape

Shape of the matrix (number of rows, number of columns).

Type:

tuple

values

The underlying data values, whether sparse or dense.

Type:

np.ndarray

is_sparse

Whether the matrix is stored in sparse format.

Type:

bool

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index/column values.

reindex(new_index, new_columns, fill_value=0.0)

Reindex the matrix to new row and column indices, filling missing values with fill_value.

round_index(decimals, axis='both')

Round the index and/or columns to a specified number of decimal places for alignment.

copy()

Return a copy of the Matrix.

to_frame()

Convert to a DataFrame.

to_dense()

Return a copy of the matrix with dense internal storage.

to_sparse(threshold=None)

Return a copy of the matrix with sparse internal storage, zeroing values below the threshold.

to_numpy()

Get the underlying data as a NumPy array.

data: DataFrame

__init__(data, name=None, index=None, columns=None, dtype=None, copy=None, sparse=False)

Initialize a Matrix.

Parameters:

• data (np.ndarray or pd.DataFrame or Matrix or scalar) – 2D data representing the matrix.

• name (str, optional) – Name for the Matrix.

• index (pd.MultiIndex) – Index for the rows of the DataFrame.

• columns (pd.MultiIndex, optional) – Index for the columns of the DataFrame. If None, uses the same as index.

• dtype (data type, optional) – Data type to force.

• copy (bool, optional) – Whether to copy the data.

• sparse (bool, default False) – If True, store the assembled matrix in pandas sparse format. Sparsification is applied after block assembly; use threshold zeroing in your builder before passing data here.

Returns:

Instance of Matrix wrapping the DataFrame.

Return type:

Matrix

__repr__()

Return string representation.

__getitem__(block)

Get the submatrix DataFrame for the given (row_block, col_block) tuple.

Return type:

DataFrame

property blocks: _MatrixBlockAccessor

Accessor for retrieving MatrixBlock instances from the Matrix.

__add__(other)

Add two Matrix instances.

Parameters:

other (Matrix) – Another Matrix instance or a scalar to add.

Returns:

Sum of the two Matrix instances.

Return type:

Matrix

scale(factor)

Scale the matrix by a scalar factor.

Parameters:

factor (float or int) – Scalar factor to multiply the matrix by.

Returns:

New Matrix instance scaled by the factor.

Return type:

Matrix

to_xarray()

Convert to xarray (not implemented for base Matrix class).

CovarianceMatrix

class fips.CovarianceMatrix(data, name=None, index=None, columns=None, dtype=None, copy=None, sparse=False)

Represents a symmetric Covariance Matrix.

Covariance matrices are used to represent error covariances in the inversion framework. They can be constructed from variances and correlation matrices.

name

Name of the covariance matrix. Optional.

Type:

str

data

The underlying DataFrame containing the matrix data.

Type:

pd.DataFrame

index

Index for the rows of the CovarianceMatrix.

Type:

pd.MultiIndex

columns

Index for the columns of the CovarianceMatrix.

Type:

pd.MultiIndex

shape

Shape of the CovarianceMatrix (number of rows, number of columns).

Type:

tuple

variances

The variances (diagonal elements) of the covariance matrix, represented as a Vector.

Type:

Vector

values

The underlying data values as a NumPy array.

Type:

np.ndarray

is_sparse

Whether the data is stored in sparse format.

Type:

bool

force_symmetry(keep='lower')

Force the matrix to be perfectly symmetric by copying one triangle to the other.

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index/column values.

reindex(new_index, new_columns, fill_value=0.0)

Reindex the matrix to new row and column indices, filling missing values with fill_value.

round_index(decimals, axis='both')

Round the index and/or columns to a specified number of decimal places for alignment.

copy()

Return a copy of the CovarianceMatrix.

to_frame(add_block_level=False)

Convert to a DataFrame, optionally adding block levels to the index and columns.

to_dense()

Return a copy of the matrix with dense internal storage.

to_sparse(threshold=None)

Return a copy of the matrix with sparse internal storage, zeroing values below the threshold.

to_numpy()

Get the underlying data as a NumPy array.

property variances: Vector

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

force_symmetry(keep='lower')

Force the matrix to be perfectly symmetric by copying one triangle to the other.

Useful for eliminating floating-point asymmetry.

Parameters:

keep ({'lower', 'upper'}, default 'lower') – Which triangle of the matrix to preserve and copy.

Returns:

A new, perfectly symmetric covariance matrix.

Return type:

CovarianceMatrix

ForwardOperator

class fips.ForwardOperator(data, name=None, index=None, columns=None, dtype=None, copy=None, sparse=False)

Forward operator matrix mapping state vectors to observation space.

A ForwardOperator wraps a pandas DataFrame and provides methods to convolve state vectors through the operator to produce modeled observations.

The foward operator, or Jacobian matrix, is a key component of inverse problems. It defines how changes in the state vector affect the observations. The rows correspond to observations and the columns to state variables.

name

Name of the forward operator. Optional.

Type:

str

data

The underlying DataFrame containing the operator data.

Type:

pd.DataFrame

index

Index for the rows of the ForwardOperator.

Type:

pd.MultiIndex

obs_index

Alias for index, representing the observation space index.

Type:

pd.MultiIndex

columns

Index for the columns of the ForwardOperator.

Type:

pd.MultiIndex

state_index

Alias for columns, representing the state space index.

Type:

pd.MultiIndex

shape

Shape of the ForwardOperator (number of rows, number of columns).

Type:

tuple

values

The underlying data values as a NumPy array.

Type:

np.ndarray

is_sparse

Whether the data is stored in sparse format.

Type:

bool

convolve(state, round_index=None, verify_overlap=True)

Convolve a state vector through the forward operator.

xs(key, axis=0, level=None, drop_level=True)

Cross-select data based on index/column values.

reindex(new_index, new_columns, fill_value=0.0)

Reindex the matrix to new row and column indices, filling missing values with fill_value.

round_index(decimals, axis='both')

Round the index and/or columns to a specified number of decimal places for alignment.

copy()

Return a copy of the ForwardOperator.

to_frame(add_block_level=False)

Convert to a DataFrame, optionally adding block levels to the index and columns.

to_dense()

Return a copy of the matrix with dense internal storage.

to_sparse(threshold=None)

Return a copy of the matrix with sparse internal storage, zeroing values below the threshold.

to_numpy()

Get the underlying data as a NumPy array.

property state_index: Index

Return the state space index (columns).

property obs_index: Index

Return the observation space index (rows).

convolve(state, round_index=None, verify_overlap=True)

Convolve a state vector through the forward operator.

Return type:

Series

Inverse Problem

class fips.InverseProblem(obs, prior, forward_operator, modeldata_mismatch, prior_error, constant=None, round_index=6)

Inverse problem combining observations, priors, and forward model.

Organizes state vectors, observations, forward operators, and error covariances into a unified framework for solving inverse problems via different estimators.

obs

Observation vector.

Type:

Vector

prior

Prior state vector.

Type:

Vector

forward_operator

Forward operator mapping state space to observation space.

Type:

ForwardOperator

modeldata_mismatch

Covariance matrix representing model-data mismatch (observation error).

Type:

CovarianceMatrix

prior_error

Covariance matrix representing prior error.

Type:

CovarianceMatrix

constant

Optional constant term added to the forward model (e.g., background or bias).

Type:

Vector or float, optional

estimator

The fitted estimator after solving the problem. Initially None until .solve() is called.

Type:

Estimator, optional

posterior

Posterior state estimate after solving the problem.

Type:

Vector

posterior_error

Posterior error covariance after solving the problem.

Type:

CovarianceMatrix

posterior_obs

Modeled observations using the posterior state.

Type:

Vector

prior_obs

Modeled observations using the prior state.

Type:

Vector

kalman_gain

Kalman gain matrix (K) after solving the problem.

Type:

Matrix

averaging_kernel

Averaging kernel matrix (A) after solving the problem.

Type:

Matrix

get_block(component, block, crossblock=None)

Retrieve a specific block of data from a component (Vector or Matrix).

solve(estimator, \*\*kwargs)

Solve the inverse problem using the specified estimator and store the fitted estimator.

__init__(obs, prior, forward_operator, modeldata_mismatch, prior_error, constant=None, round_index=6)

Initialize the inverse problem.

Parameters:

• obs (VectorLike) – Observation vector.

• prior (VectorLike) – Prior state vector.

• forward_operator (MatrixLike) – Forward operator mapping state space to observation space.

• modeldata_mismatch (MatrixLike) – Covariance matrix representing model-data mismatch (observation error).

• prior_error (MatrixLike) – Covariance matrix representing prior error.

• constant (VectorLike or float, optional) – Optional constant term added to the forward model (e.g., background or bias).

• round_index (int, optional) – Number of decimal places to round to. If None, no rounding is performed.

property state_index: Index

Return the state space index.

property obs_index: Index

Return the observation space index.

property n_state: int

Return number of state variables.

property n_obs: int

Return number of observations.

property estimator: Estimator

Return the fitted estimator (raises if not solved).

get_block(component, block, crossblock=None)

Get block from a component (Vector or Matrix).

Parameters:

• component (str) – Name of the component (‘obs’, ‘prior’, ‘forward_operator’, ‘modeldata_mismatch’, ‘prior_error’, or ‘constant’).

• block (str) – Name of the block to retrieve.

• crossblock (str, optional) – For matrices, the name of the cross block (e.g., ‘state’ for forward_operator). If None, defaults to the same as ‘block’.

Returns:

The requested block of data.

Return type:

pd.Series or pd.DataFrame

solve(estimator, **kwargs)

Solve the inverse problem using the specified estimator.

Parameters:

• estimator (str or type[Estimator]) – Estimator to use for solving the inverse problem. Can be a string key for registered estimators or a subclass of Estimator.

• **kwargs – Additional keyword arguments to pass to the estimator.

Returns:

The InverseProblem instance with the estimator fitted.

Return type:

Self

__getstate__()

Explicit pickle support: return state as dict.

__setstate__(state)

Explicit pickle support: restore state from dict.

__repr__()

Return string representation.

Return type:

str

property posterior: Vector

Posterior state estimate.

property posterior_error: CovarianceMatrix

Posterior error covariance.

property posterior_obs: Vector

Modeled observations (H @ posterior).

property prior_obs: Vector

Modeled observations using the prior (H @ prior).

property kalman_gain: Matrix

Kalman gain matrix (K).

property averaging_kernel: Matrix

Averaging kernel matrix (A).

Estimators

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.

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

Returns:

Posterior observation estimate.

Return type:

np.ndarray

property y_0: ndarray

Prior mean data estimate.

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

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

\[\begin{split}\\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))\end{split}\]

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

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

Returns:

R-squared value.

Return type:

float

property RMSE: float

Root mean square error (RMSE).

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

Returns:

RMSE value.

Return type:

float

property uncertainty_reduction: float

Uncertainty reduction metric.

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

Returns:

Uncertainty reduction value.

Return type:

float

property U_red: ndarray

Uncertainty reduction vector.

\[\begin{split}U_{red} = \\left( 1 - \\frac{\\sqrt{diag(\\hat{S})}}{\\sqrt{diag(S_0)}} \\right) * 100\\%\end{split}\]

Returns:

Uncertainty reduction vector.

Return type:

np.ndarray

Inversion estimators for solving inverse problems.

This module contains Bayesian and regularized estimators for state estimation in linear inverse problems, computing posterior distributions and diagnostics.

fips.estimators.available_estimators()

Return the names of all registered estimators.

Returns:

Names that can be passed to solve().

Return type:

list of str

class fips.estimators.BayesianSolver(z, x_0, H, S_0, S_z, c=None, rf=1.0)

Bayesian inversion estimator class.

This class implements a Bayesian inversion framework for solving inverse problems, also known as the batch method.

__init__(z, x_0, H, S_0, S_z, c=None, rf=1.0)

Initialize inversion object.

Parameters:

• z (np.ndarray) – Observed data

• x_0 (np.ndarray) – Prior model estimate

• H (np.ndarray) – Forward operator

• S_0 (np.ndarray) – Prior error covariance

• S_z (np.ndarray) – Model-data mismatch covariance

• c (np.ndarray | float, optional) – Constant data, defaults to 0.0

• rf (float, optional) – Regularization factor, by default 1.0

__repr__()

Return string representation.

Return type:

str

cost(x)

Cost function.

\[\begin{split}J(x) = \\frac{1}{2}(x - x_0)^T S_0^{-1}(x - x_0) + \\frac{1}{2}(z - Hx - c)^T S_z^{-1}(z - Hx - c)\end{split}\]

property x_hat

Posterior Mean Model Estimate (solution).

\[\begin{split}\\hat{x} = x_0 + K(z - Hx_0 - c)\end{split}\]

property S_hat

Posterior Error Covariance Matrix.

\[\begin{split}\\hat{S} = (H^T S_z^{-1} H + S_0^{-1})^{-1} = S_0 - (H S_0)^T(H S_0 H^T + S_z)^{-1}(H S_0)\end{split}\]

Pipeline

class fips.pipeline.InversionPipeline(config, problem, estimator)

Blueprint for inversion.

This class defines the standard workflow for running an inversion, including methods for loading observations and priors, building the forward operator and covariance matrices, and executing the solve process.

Subclasses should implement the abstract methods to handle the specifics of data loading and covariance construction for their particular problem domain.

get_obs()

Get observation vector.

get_prior()

Get prior state vector.

filter_state_space(obs, prior)

Align or trim the state space before building covariances.

get_forward_operator(obs, prior)

Get forward operator matrix.

get_prior_error(prior)

Get prior error covariance matrix.

get_modeldata_mismatch(obs)

Get model-data mismatch covariance matrix.

get_constant(obs)

Get optional constant offset vector.

aggregate_obs_space(obs, forward_operator, modeldata_mismatch, constant)

Aggregate the observation space.

get_inputs()

Gather all input components for the inverse problem.

run(**kwargs)

Execute the standard inversion workflow.

__init__(config, problem, estimator)

abstract get_obs()

Get observation vector.

Return type:

Vector

abstract get_prior()

Get prior state vector.

Return type:

Vector

filter_state_space(obs, prior)

Align or trim the state space before building covariances.

Optionally filter the state space by removing intervals with insufficient observations or simulations.

Return type:

tuple[Vector, Vector]

abstract get_forward_operator(obs, prior)

Get forward operator matrix.

Return type:

ForwardOperator

abstract get_prior_error(prior)

Get prior error covariance matrix.

Return type:

CovarianceMatrix

abstract get_modeldata_mismatch(obs)

Get model-data mismatch covariance matrix.

Return type:

CovarianceMatrix

get_constant(obs)

Get optional constant offset vector.

Return type:

Vector | None

aggregate_obs_space(obs, forward_operator, modeldata_mismatch, constant)

Aggregate the observation space.

Optionally aggregate the observation space (e.g. hourly → daily) by applying the same aggregation to the obs vector, forward operator, model-data mismatch covariance, and constant term.

Return type:

tuple[Vector, ForwardOperator, CovarianceMatrix, Vector | None]

get_inputs()

Gather all input components for the inverse problem.

Return type:

dict[str, Any]

run(**kwargs)

Execute the standard inversion workflow.

Return type:

TypeVar(_Problem, bound= InverseProblem)

Flux Inversion

class fips.problems.flux.pipeline.FluxInversionPipeline(config)

Abstract pipeline for atmospheric flux inversions.

config

Configuration object containing pipeline settings.

Type:

Any

problem

The solved flux inversion problem (available after calling run()).

Type:

FluxProblem

estimator

Estimator to use for solving the inverse problem.

Type:

str or type[Estimator]

get_obs()

Get observation vector (abstract, must be implemented by subclass).

get_prior()

Get prior state vector (abstract, must be implemented by subclass).

filter_state_space(obs, prior)

Filter state space by removing intervals with insufficient observations.

get_forward_operator(obs, prior)

Get forward operator matrix (abstract, must be implemented by subclass).

get_prior_error(prior)

Get prior error covariance matrix (abstract, must be implemented by subclass).

get_modeldata_mismatch(obs)

Get model-data mismatch covariance matrix (abstract, must be implemented by subclass).

get_constant(obs)

Get optional constant offset vector.

aggregate_obs_space(obs, forward_operator, modeldata_mismatch, constant)

Aggregate the observation space.

get_inputs()

Gather all input components for the inverse problem.

run(**kwargs)

Execute the flux inversion workflow and print summary.

summarize()

Print comprehensive statistical summary of the inversion results.

problem: FluxProblem

__init__(config)

filter_state_space(obs, prior)

Filter state space by removing intervals with insufficient observations.

Parameters:

• obs (Vector) – Observation vector.

• prior (Vector) – Prior state vector.

Returns:

Filtered observation and prior vectors.

Return type:

tuple[Vector, Vector]

run(**kwargs)

Run the flux inversion pipeline.

Parameters:

**kwargs – Additional keyword arguments passed to the inverse problem initialization.

Returns:

The solved flux inversion problem.

Return type:

FluxProblem

summarize()

Print a comprehensive statistical summary of the inversion results.

Return type:

None

class fips.problems.flux.visualization.FluxPlotter(inversion)

Plotting interface for FluxInversion results.

Provides methods for visualizing prior/posterior fluxes and concentration timeseries.

inversion

The flux inversion problem to visualize.

Type:

FluxProblem

fluxes(time='mean', truth=None, x_dim='lon', y_dim='lat', time_dim='time', sites=False, sites_kwargs=None, \*\*kwargs)

Plot prior and posterior flux maps.

concentrations(location=None, location_dim='obs_location', \*\*kwargs)

Plot observed, prior, and posterior concentrations.

__init__(inversion)

Initialize with a FluxInversion instance.

Parameters:

inversion (FluxInversion) – The inverse problem to visualize.

__repr__()

Return string representation.

Return type:

str

fluxes(time='mean', truth=None, x_dim='lon', y_dim='lat', time_dim='time', sites=False, sites_kwargs=None, **kwargs)

Plot prior and posterior flux maps.

Parameters:

• time (str, int, or pd.Timestamp, default 'mean') – Time to plot: ‘mean’, ‘std’, time index, or timestamp.

• truth (pd.Series, optional) – Truth fluxes for comparison.

• x_dim (str, default 'lon') – Name of the x-coordinate dimension.

• y_dim (str, default 'lat') – Name of the y-coordinate dimension.

• time_dim (str, default 'time') – Name of the time dimension.

• sites (bool or dict, optional) – Site locations to overlay: dict mapping site IDs to (lat, lon).

• sites_kwargs (dict, optional) – Additional plotting kwargs for site markers.

• **kwargs – Additional arguments passed to xarray plotting.

Returns:

fig, axes – The created figure and axes.

Return type:

matplotlib Figure and Axes

concentrations(location=None, location_dim='obs_location', **kwargs)

Plot observed, prior, and posterior concentrations.

Parameters:

• location (str, list of str, optional) – Observation location(s) to plot. If None, plots all locations.

• location_dim (str, default 'obs_location') – Name of the location dimension in the data.

• **kwargs – Additional arguments passed to pandas plotting.

Returns:

axes – Array of axes objects, one per location.

Return type:

np.ndarray

Utilities

convolve

fips.convolve(state, forward_operator, round_index=None, verify_overlap=True)

Convolve a state vector with a forward operator matrix.

Parameters:

• state (Vector, pd.Series, or np.ndarray) – State vector to convolve. Can be a Vector, Series, or 1D array.

• forward_operator (ForwardOperator or pd.DataFrame) – Forward operator matrix to convolve with. Can be a ForwardOperator or a DataFrame.

• round_index (int, optional) – Number of decimal places to round indices for alignment. If None, no rounding is done.

• verify_overlap (bool, optional) – Whether to verify that the state index overlaps with the operator’s state index. Defaults to True.

Returns:

The convolved observation vector.

Return type:

pd.Series

Indexes

Index validation and manipulation utilities.

This module provides utilities for checking index overlap, promoting indices, and sanitizing index types for consistent handling across data structures.

fips.indexes.apply_to_index(func)

Apply a single-index function to each level of a MultiIndex.

Parameters:

func (function) – A function that takes a single pd.Index and returns a modified pd.Index. This function will be applied to each level of a MultiIndex, or directly to a single Index.

Returns:

A wrapper function that applies the given function to each level of a MultiIndex or to a single Index.

Return type:

function

fips.indexes.assign_block(index, block)

Assign or overwrite a ‘block’ level in the index.

Parameters:

• index (pd.Index) – The original index to which the block level will be assigned.

• block (str) – The block name to assign to the index.

Returns:

A new index with the ‘block’ level assigned to the specified block name.

Return type:

pd.Index

fips.indexes.outer_align_levels(dfs, axis=0, fill_value=nan)

Align MultiIndexes by performing an OUTER JOIN on level names.

Strictly preserves the order of appearance (First-Seen Priority).

Parameters:

• dfs (list of pd.DataFrame) – The DataFrames to align.

• axis (int or 'both', default 0) – The axis along which to align the DataFrames. 0 or ‘index’ for row alignment, 1 or ‘columns’ for column alignment, ‘both’ for both axes.

• fill_value (scalar, default np.nan) – The value to use for missing entries after alignment. By default, missing entries are filled with NaN.

Returns:

A list of DataFrames with aligned MultiIndexes along the specified axis.

Return type:

list of pd.DataFrame

fips.indexes.overlaps(target_idx, available_idx)

Check if target index overlaps with available index.

Returns True if fully covered, ‘partial’ if partially covered, and False if no overlap.

Parameters:

• target_idx (pd.Index) – The index we want to check for coverage.

• available_idx (pd.Index) – The index that represents available data.

Returns:

True if target_idx is fully covered by available_idx, ‘partial’ if partially covered, and False if no overlap.

Return type:

bool or ‘partial’

fips.indexes.resolve_axes(axis)

Standardize axis input into a tuple of integer axes.

Return type:

tuple[int, ...]

fips.indexes.round_index(index, decimals)

Round float indices to specified decimals.

Parameters:

• index (pd.Index) – The index to round.

• decimals (int) – The number of decimal places to round to.

Returns:

A new index with float values rounded to the specified number of decimals. Non-float indices are returned unchanged.

Return type:

pd.Index

fips.indexes.to_numeric(index)

Attempt to convert index to numeric types.

Parameters:

index (pd.Index) – The index to convert.

Returns:

A new index with values converted to numeric types where possible. Non-convertible values are returned unchanged.

Return type:

pd.Index

Kernels

Covariance kernel functions.

This module provides kernel functions for generating covariance matrices, such as exponential decay, constant correlation, and other spatial/temporal correlation structures.

fips.kernels.ConstantCorrelation()

Return a constant 1.0 correlation callable.

fips.kernels.RaggedTimeDecay(time_dim, scale, decay_func=<function _exponential_decay>)

Create a ragged temporal decay kernel.

Defaults to exponential decay, but can accept any math function.

Parameters:

• time_dim (str) – Name of the time dimension in the input DataFrame.

• scale (str or pd.Timedelta) – Scale parameter for the decay function. If a string is provided, it will be converted to a pd.Timedelta.

• decay_func (callable, optional) – A function that takes a distance matrix and a scale parameter and returns a decay matrix. Defaults to the exponential decay function.

Returns:

A kernel function that can be applied to a DataFrame to compute the temporal decay matrix based on the specified time dimension and scale.

Return type:

function

fips.kernels.GridTimeDecay(scale, decay_func=<function _exponential_decay>)

Create a grid temporal decay kernel.

Parameters:

• scale (str or pd.Timedelta) – Scale parameter for the decay function. If a string is provided, it will be converted to a pd.Timedelta.

• decay_func (callable, optional) – A function that takes a distance matrix and a scale parameter and returns a decay matrix. Defaults to the exponential decay function.

Returns:

A kernel function that can be applied to a DataFrame to compute the temporal decay matrix based on the specified scale, treating all time points as part of a single grid (i.e., not grouped by any time dimension).

Return type:

function

fips.kernels.GridSpatialDecay(lat_dim, lon_dim, scale, decay_func=<function _exponential_decay>)

Create a grid spatial decay kernel (Haversine).

Parameters:

• lat_dim (str) – Name of the latitude dimension in the input DataFrame.

• lon_dim (str) – Name of the longitude dimension in the input DataFrame.

• scale (float) – Scale parameter for the decay function, in the same units as the distance matrix (e.g., kilometers if using Haversine distance).

• decay_func (callable, optional) – A function that takes a distance matrix and a scale parameter and returns a decay matrix. Defaults to the exponential decay function.

Returns:

A kernel function that can be applied to a DataFrame to compute the spatial decay matrix based on the specified latitude and longitude dimensions and scale, using Haversine distance for spatial separation.

Return type:

function

Filters

Data filtering and selection utilities.

This module provides functions for filtering observations and state vectors based on various criteria, such as data density, time intervals, and quality control thresholds.

fips.filters.enough_obs_per_interval(index, intervals, threshold, level=None)

Determine which observations have enough data points per time interval.

Parameters:

• index (pd.Index) – Index containing observations.

• intervals (pd.IntervalIndex) – Intervals to group observations into.

• threshold (int) – Minimum number of observations required per interval.

• level (str, optional) – Level name to use if index is a MultiIndex. If None, uses the entire index.

Returns:

Boolean mask indicating which observations meet the threshold.

Return type:

list[bool]

fips.filters.select_intervals_with_min_obs(data, intervals, threshold, level=None)

Filter data to only include observations with enough data points per time interval.

Parameters:

• data (pd.Series | pd.DataFrame) – Data to filter.

• intervals (pd.IntervalIndex) – Intervals to group observations into.

• threshold (int) – Minimum number of observations required per interval.

• level (str, optional) – Level name to use if index is a MultiIndex. If None, uses the entire index.

Returns:

Filtered data.

Return type:

pd.Series | pd.DataFrame

Metrics

Distance and similarity metrics.

This module provides functions for calculating distances and similarities between data points, such as Haversine distance for geographic coordinates and time differences for temporal data.

fips.metrics.haversine_matrix(lats, lons, earth_radius=None, deg=True)

Calculate the pairwise Haversine distance matrix between a set of coordinates.

Parameters:

• lats (array-like) – 1D array-like of latitude coordinates in degrees (if deg=True) else in radians.

• lons (array-like) – 1D array-like of longitude coordinates in degrees (if deg=True) else in radians.

• earth_radius (float, optional) – Radius of the Earth in kilometers, by default 6371.0 km.

• deg (bool, optional) – If True, input coordinates are in degrees and will be converted to radians. If False, input coordinates are assumed to be in radians, by default True.

Returns:

A 2D NumPy array (matrix) where the element at (i, j) is the Haversine distance between the i-th and j-th coordinate. The diagonal of the matrix will be zero.

Return type:

np.ndarray

fips.metrics.time_diff_matrix(times, absolute=True)

Calculate the time differences between each pair of times.

Parameters:

• times (list[dt.datetime]) – The list of times to calculate the differences between.

• absolute (bool, optional) – If True, return the absolute differences. Default is True.

Returns:

The matrix of time differences.

Return type:

np.ndarray

Aggregators

Data aggregation utilities for inverse problems.

This module provides functions for aggregating and integrating data over time and space, particularly useful for processing observations and state vectors into compatible resolutions.

fips.aggregators.integrate_over_time_bins(data, time_bins, time_dim='time')

Integrate data over time bins.

Parameters:

• data (pd.DataFrame | pd.Series) – Data to integrate.

• time_bins (pd.IntervalIndex) – Time bins for integration.

• time_dim (str, optional) – Time dimension name, by default ‘time’

Returns:

Integrated footprint. The bin labels are set to the left edge of the bin.

Return type:

pd.DataFrame | pd.Series

class fips.aggregators.ObsAggregator(by=None, level=None, freq=None, func='mean', blocks=None)

Aggregates the observation space of an inverse problem.

Builds a sparse (n_agg x n_obs) weight matrix W and applies it to each component of the problem:

z_agg = W @ z  # aggregated observations
H_agg = W @ H  # aggregated forward operator
S_z_agg = W @ S_z @ W.T  # covariance propagation
c_agg = W @ c  # aggregated constant (if vector)

For func='mean' each non-zero entry in row i equals 1/nᵢ (the reciprocal of the group size), so W @ z yields group means and W @ S_z @ W.T scales variances by 1/nᵢ². For func='sum' every entry is 1. Only 'mean' and 'sum' are supported because other functions do not have a well-defined covariance propagation rule.

Grouping interface

Exactly one of by or level must be provided:

• by : an index level name (str), a list of level names, or a callable that accepts the obs pd.Index and returns group labels.

• level + freq : resample a datetime index level at the given pandas offset alias (e.g. level='obs_time', freq='D'). All other index levels are preserved as exact-match grouping keys.

When the obs index has a 'block' level it is always prepended as a grouping key, ensuring observations from different blocks are never merged.

Partial aggregation

blocks restricts aggregation to the named block(s). Observations belonging to other blocks are passed through unchanged via identity rows in W, so the returned arrays cover the full observation space.

apply(obs, forward_operator, modeldata_mismatch, constant)

Apply the aggregation to the inverse problem components.

__init__(by=None, level=None, freq=None, func='mean', blocks=None)

Initialize the ObsAggregator.

Parameters:

• by (str | list[str] | Callable, optional) – Explicit grouping specification. Mutually exclusive with level.

• level (str, optional) – Index level to group / resample. Requires either a matching level name in the obs index or use alongside freq.

• freq (str, optional) – Pandas offset alias for resampling level (e.g. 'D', 'h').

• func ({'mean', 'sum'}) – Aggregation function. Default 'mean'.

• blocks (str | list[str], optional) – Block name(s) to aggregate. Unlisted blocks pass through as-is.

apply(obs, forward_operator, modeldata_mismatch, constant=None)

Apply W to the inverse problem components.

Inputs may be bare pandas objects or fips wrapper types (Vector, ForwardOperator, CovarianceMatrix); return types mirror the inputs. See the class docstring for the mathematical transforms.

The aggregator ensures all inputs are properly aligned to obs.index before building the weight matrix W.

Parameters:

• obs (pd.Series | Block | Vector) – Observation vector to be aggregated.

• forward_operator (pd.DataFrame | MatrixBlock | Matrix) – Forward operator matrix to be aggregated.

• modeldata_mismatch (pd.DataFrame | MatrixBlock | Matrix) – Model-data mismatch covariance matrix to be aggregated.

• constant (float | pd.Series | Block | Vector | None, optional) – Optional constant offset vector to be aggregated. Scalars are invariant to aggregation. Default is None.

Returns:

Aggregated (obs, forward_operator, modeldata_mismatch, constant) in the same types as the inputs.

Return type:

tuple