fips.Operator#

class fips.Operator(data, rows, cols, name=None)[source]#

A matrix with a Space of labels on each axis.

The matrix is kept in its cheapest form (data, one of the forms of fips.linalg): a dense array, a SciPy sparse matrix, a diagonal, Kronecker factors. Its rows are labeled by rows and its columns by cols, in the order of each space. Products, sums and selections check the labels: two operators combine only when the spaces they meet on have the same labels, in any order (an exact join).

An operator is not changed in place: every method returns a new one. NumPy defers to it (__array_ufunc__ = None), so np.float64(2) * op is an operator and array + op raises, as op + array does.

Parameters:

data (LinearOperator | sp.spmatrix | sp.sparray | npt.ArrayLike) – The matrix, with rows in the order of rows and columns in the order of cols. An array or a sparse matrix is copied, and the copy is read-only: changing data afterwards leaves the operator as it was. A sparse matrix stays sparse (a diagonal one becomes a DiagonalOperator); a form of fips.linalg already holds its own copy and is kept as it is. A DataFrame is refused, since its labels would be ignored: use from_frame(). So is an Operator: use align() to put it on other labels, or its data for the matrix by position.
rows (Space) – The labels of the rows.
cols (Space) – The labels of the columns.
name (str | None) – What the matrix is (“forward”, “prior_cov”, …). A name that is not a string is converted to one.

Raises:

TypeError – If data is a pandas object or an Operator, or rows or cols is not a Space.
ValueError – If the shape of data does not match the spaces, or it stores a NaN.

See also

Operator.from_frame: An operator from a labeled DataFrame.
Operator.from_blocks: An operator from its blocks.
fips.Covariance: A symmetric operator on one space.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from fips import Operator, Space, Vector
>>> state = Space({"flux": pd.Index(["a", "b"], name="cell")})
>>> obs = Space({"co2": pd.Index([1, 2, 3], name="obs_id")})
>>> H = Operator(np.array([[1.0, 0.0], [0.0, 1.0], [1.0, 1.0]]), obs, state)
>>> H.shape
(3, 2)
>>> x = Vector([2.0, 3.0], state)
>>> (H @ x).values
array([2., 3., 5.])

Attributes

`cols`	The labels of the columns.
`data`	The matrix, in its form (a `fips.linalg` operator, without labels).
`name`	a string, or None.
`rows`	The labels of the rows.
`shape`	The number of rows and of columns.
`T`	the columns become the rows, labels and all.

Methods

`align`(rows, cols)	Return the operator on rows and cols, which must have exactly its labels.
`dense`()	Return the matrix as a new dense array, rows and columns in the spaces' order.
`from_blocks`(blocks[, rows, cols, name])	Build an operator from its blocks, each named by its row and its column block.
`from_frame`(frame[, row_block, col_block, name])	Build an operator from a DataFrame, reading its labels.
`round_labels`(decimals)	Return the operator with its float labels rounded (`Space.round_labels()`).
`sparse`()	Return the matrix as a new SciPy CSR array, rows and columns in the spaces' order.
`to_frame`()	Return the matrix as a dense DataFrame.