fips.Covariance

class fips.Covariance(data, space, name=None)

Bases: Operator

A covariance: a symmetric operator from a Space to itself.

The matrix is kept in its cheapest form, as an Operator’s is: a diagonal covariance is its variances, a Kronecker one its factors, a block diagonal one each block in its own form. On top of an operator’s methods it gives the variances and, for a positive-definite covariance, solve(), logdet(), quadratic_form() and sqrt(), each done the way its form makes cheap.

Parameters:

• data (LinearOperator | sp.spmatrix | sp.sparray | npt.ArrayLike) – The matrix, square, rows and columns in the order of space. An array or a sparse matrix is copied, and the copy is read-only, as for an Operator.

• space (Space) – The labels of both axes.

• name (str | None) – What the covariance is (“prior_cov”, “obs_cov”, …).

Raises:

• TypeError – If data is a pandas object or an Operator (its labels would be ignored: use cov.align(space, space), or cov.data for the matrix), or space is not a Space.

• ValueError – If the matrix does not have one row and one column per label, it stores a NaN, or a dense or sparse matrix is not symmetric: its largest |A - A^T| is more than 1e-10 of its largest entry (the message names the two entries and their labels). A diagonal or Kronecker form is symmetric by construction, and a block diagonal one is checked block by block. Also if the matrix is not positive semidefinite: an eigenvalue is below zero by more than roundoff, n * eps times the largest (the message names the smallest).

Notes

The positive semidefinite check is the root sample() draws with, built here and kept: the Cholesky factor of a dense matrix (n^3 / 3 operations, and n x n more memory), of each group of correlated rows of a sparse one, of each block of a block diagonal one and of each factor of a Kronecker one, or the square roots of a diagonal. A singular matrix, which has no Cholesky factor, is eigendecomposed instead (several times the cost), with one INFO line. A covariance fips builds from a correlation model or computes (a sum, a reordering, a posterior) is positive semidefinite by construction and is not checked.

See also

Covariance.diagonal

A covariance from its variances.

Covariance.block_diag

Independent covariances side by side.

fips.Exponential

A correlation model, which with_std makes a covariance.

Operator.from_frame

A covariance from a labeled DataFrame.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from fips import Covariance, Space, Vector
>>> space = Space({"flux": pd.Index(["a", "b"], name="cell")})
>>> S = Covariance(np.array([[2.0, 1.0], [1.0, 2.0]]), space)
>>> S.variances.values
array([2., 2.])
>>> S.solve(Vector([3.0, 3.0], space)).values
array([1., 1.])

Attributes

space	The labels of both axes.
variances	the diagonal, as a vector on the covariance's space.

Methods

aggregate(W)	Return the covariance of aggregates, \(W S W^T\).
block_diag(*covariances[, name])	Put independent covariances side by side: each on its own blocks, zero between.
diagonal(values[, space, name])	Build a diagonal covariance from its variances.
logdet()	Return log(det(S)), from the form's factors (see fips.linalg.LinearOperator.logdet()).
quadratic_form(x)	Return \(x^T S^{-1} x\), the squared Mahalanobis length of x.
sample([rng])	Return one draw from \(N(0, S)\), a vector on the covariance's space.
solve(b)	Return \(S^{-1} b\), for a positive-definite covariance \(S\).
sqrt()	Return a square root \(L\), with \(L L^T = S\).

Inherited

From Operator: align, cols, data, dense, from_blocks, from_frame, name, round_labels, rows, shape, sparse, T, to_frame