Skip to content

uncertainty.covariance

Covariances of uncertain values: the dependence between them.

A Covariance is the dependence of a set of uncertain values (the inputs of a simulation or the parameters of a model), given as a covariance matrix or as a correlation: a full matrix or the coefficients of pairs. The same object is used by every step of an uncertainty analysis, see sbmlsim.uncertainty.

A covariance is in the units of its targets (units, the entry ij in the unit of i times the unit of j), on the linear scale or on the log scale (scale="log", e.g. the omega matrix of a population analysis of log-normal parameters). A correlation is dimensionless; the standard deviations come from the marginals of its targets.

Every matrix is validated: square, symmetric, finite, a positive diagonal (unit for a correlation, |rho| <= 1) and positive semi-definite. A correlation which is not positive semi-definite, e.g. assembled from the coefficients of several sources, can be replaced by the nearest correlation matrix (nearest=True, Higham 2002).

Higham NJ (2002). Computing the nearest correlation matrix: a problem from finance. IMA J Numer Anal 22:329-343.

Covariance dataclass 

Covariance(
    targets,
    matrix,
    units=None,
    scale="linear",
    kind="covariance",
)

The dependence of uncertain values, see the module.

Attributes:

Name Type Description
targets tuple[str, ...]

the targets, the names of the uncertain values.
matrix ndarray

the read-only matrix, a covariance or a correlation.
kind Literal['covariance', 'correlation']

covariance or correlation.
scale Literal['linear', 'log']

the scale of a covariance, linear or log.
units tuple[str | None, ...] | None

the unit of every target of a covariance, None without.

Create a covariance (or a correlation, see correlation).

Parameters:

Name Type Description Default
targets Sequence[str]

the targets in the order of the rows.

 required
matrix ArrayLike

the matrix.

 required
units Sequence[str | None] | None

the unit of every target, for a covariance.

 None
scale Literal['linear', 'log']

linear or log, for a covariance.

 'linear'
kind Literal['covariance', 'correlation']

covariance or correlation.

 'covariance'

Raises:

Type Description
ValueError

if the matrix is not valid, see the module.

correlation classmethod 

correlation(
    pairs=None, *, matrix=None, targets=None, nearest=False
)

Create a correlation, from the coefficients of pairs or a matrix.

Parameters:

Name Type Description Default
pairs Mapping[tuple[str, str], float] | None

(a, b) -> rho, the other pairs are uncorrelated; the targets in the order they appear.

 None
matrix ArrayLike | None

a full correlation matrix, with targets.

 None
targets Sequence[str] | None

the targets of the matrix.

 None
nearest bool

replace a matrix which is not positive semi-definite by the nearest correlation matrix, with a warning.

 False

Returns:

Type Description
Covariance

The correlation.

Raises:

Type Description
ValueError

for pairs and a matrix together or neither, a matrix without targets, or a matrix which is not valid.

sds 

sds()

Get the standard deviations of a covariance, None for a correlation.

correlation_matrix 

correlation_matrix()

Get the correlation matrix.

to_dict 

to_dict()

Get the covariance as a dictionary of JSON types.

from_dict classmethod 

from_dict(d)

Create a covariance from to_dict.

nearest_correlation 

nearest_correlation(matrix, max_iterations=100, tol=1e-10)

Get the nearest correlation matrix in the Frobenius norm.

The alternating projections method with the correction of Dykstra of Higham (2002): the projection onto the positive semi-definite matrices and onto the matrices with a unit diagonal, alternately, until the iterates change less than tol.

Parameters:

Name Type Description Default
matrix ArrayLike

a symmetric matrix with a unit diagonal.

 required
max_iterations int

the most iterations.

 100
tol float

the tolerance of the change of an iteration in the Frobenius norm.

 1e-10

Returns:

Type Description
ndarray

The nearest correlation matrix.