Operators

An Operator is a matrix with a Space of labels on each axis: a forward operator from the state to the observations, an aggregation, a gain. Its matrix is kept in the cheapest form that is exact (a dense array, a SciPy sparse matrix, a diagonal, Kronecker factors; see Linear Algebra), and the labels are beside it. Products, sums and selections check the labels: two operators combine only when the spaces they meet on have the same labels, in any order. A DataFrame is a way in (Operator.from_frame()) and a way out (Operator.to_frame()).

In [1]: import numpy as np

In [2]: import pandas as pd

In [3]: import fips

In [4]: obs = pd.Index(["o1", "o2"], name="obs_id")

In [5]: H = fips.Operator.from_blocks(
   ...:     {
   ...:         ("co2", "flux"): pd.DataFrame(
   ...:             [[1.0, 0.5], [0.0, 2.0]],
   ...:             index=obs,
   ...:             columns=pd.Index(["a", "b"], name="cell"),
   ...:         ),
   ...:         ("co2", "bias"): pd.DataFrame(
   ...:             1.0, index=obs, columns=pd.Index(["A"], name="site")
   ...:         ),
   ...:     },
   ...:     name="forward",
   ...: )
   ...: 

In [6]: H
Out[6]: 
Operator(name='forward', shape=(2, 3), form=DenseOperator)
  rows: Space(co2: 2 x ['obs_id'])
  cols: Space(flux: 2 x ['cell'], bias: 1 x ['site'])

In [7]: H["co2", "flux"].to_frame()
Out[7]: 
block        flux     
cell            a    b
block obs_id          
co2   o1      1.0  0.5
      o2      0.0  2.0

In [8]: x = fips.Vector(np.array([2.0, 1.0, 0.5]), H.cols)

In [9]: (H @ x).to_series()
Out[9]: 
block  obs_id
co2    o1        3.0
       o2        2.5
dtype: float64

Operator

Constructor

Operator(data, rows, cols[, name])	A matrix with a Space of labels on each axis.
Operator.from_frame(frame[, row_block, ...])	Build an operator from a DataFrame, reading its labels.
Operator.from_blocks(blocks[, rows, cols, name])	Build an operator from its blocks, each named by its row and its column block.

Attributes

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

Selection and labels

Operator.__getitem__(key)	Return the block of one row block and one column block.
Operator.align(rows, cols)	Return the operator on rows and cols, which must have exactly its labels.
Operator.round_labels(decimals)	Return the operator with its float labels rounded (Space.round_labels()).

Arithmetic

Operator.__matmul__(other)	Return the product with an operator or a vector, aligned by label.
Operator.__add__(other)	Return the sum with an operator on the same labels (in any order).
Operator.__sub__(other)	Return the difference with an operator on the same labels (in any order).
Operator.__mul__(scalar)	Return the operator times a scalar, in the same form.
Operator.__truediv__(scalar)	Return the operator divided by a scalar.
Operator.__neg__()	Return -self.

Conversion

Operator.dense()	Return the matrix as a new dense array, rows and columns in the spaces' order.
Operator.sparse()	Return the matrix as a new SciPy CSR array, rows and columns in the spaces' order.
Operator.to_frame()	Return the matrix as a dense DataFrame.