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

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.

Attributes

columns	Return the columns of the underlying DataFrame.
index	Return the index of the underlying data.
is_sparse	True if the internal DataFrame uses pandas sparse storage.
shape	Return the shape of the underlying data.
values	Return values as numpy array or sparse matrix.
data	The underlying data, which must be numeric and non-NaN.
name	Name of the structure, used for error messages and block naming.
row_block	Name of the row block (e.g., 'state', 'obs').
col_block	Name of the column block (e.g., 'state', 'obs').

Methods

copy([deep])	Create a copy of the structure.
from_file(path)	Load object from a pickle file.
reindex(index[, columns, verify_overlap, ...])	Return a new instance with data reindexed to the specified index and columns.
round_index(decimals[, axis, inplace])	Round float indices on the specified axis to given decimals.
to_dense()	Return a copy with dense internal storage.
to_file(path)	Save object to a pickle file.
to_frame([add_block_level])	Convert to DataFrame with optional block level.
to_numpy()	Get the underlying data as a NumPy array.
to_sparse([threshold])	Return a copy with sparse internal storage.
xs(key[, axis, level, drop_level])	Cross-select data based on index/column values.