pymixef.covariance module

Positive-definite covariance structures and diagnostics.

All estimable structures accept unconstrained optimizer parameters and construct valid covariance matrices throughout optimization. Parameters are ordered deterministically and documented by parameter_names().

class pymixef.covariance.AR1(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Homogeneous first-order autoregressive covariance.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'ar1'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, index=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• index (ArrayLike | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.AR1Covariance

alias of AR1

class pymixef.covariance.AnteDependence(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

First-order ante-dependence with stable innovation standard deviations.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'ante-dependence'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.AnteDependenceCovariance

alias of AnteDependence

class pymixef.covariance.CompoundSymmetry(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Homogeneous exchangeable covariance with a valid dimension-aware range.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'compound-symmetry'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.CompoundSymmetryCovariance

alias of CompoundSymmetry

class pymixef.covariance.CovarianceStructure(dimension=None, *, index=None, group=None)

Bases: object

Base class for covariance declarations and estimable kernels.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'covariance'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, index=None, coordinates=None)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• index (ArrayLike | None)

• coordinates (ArrayLike | None)

Return type:

NDArray[float64]

matrix(parameters, **context)

Alias for covariance().

Parameters:

• parameters (ArrayLike)

• context (Any)

Return type:

NDArray[float64]

validate(matrix, **_)

Return definiteness diagnostics or raise CovarianceError.

Parameters:

• matrix (ArrayLike)

• _ (Any)

Return type:

CovarianceValidation

derivatives(parameters, **context)

Return central finite-difference derivatives (p, n, n).

Parameters:

• parameters (ArrayLike)

• context (Any)

Return type:

NDArray[float64]

simulate(parameters, *, rng=None, draws=1, **context)

Draw zero-mean multivariate normal realizations.

Parameters:

• parameters (ArrayLike)

• rng (Generator | int | None)

• draws (int)

• context (Any)

Return type:

NDArray[float64]

to_dict()

Serialize the declaration (not estimated parameter values).

Return type:

dict[str, Any]

class pymixef.covariance.CovarianceValidation(dimension, symmetric, positive_definite, effective_rank, eigenvalues, eigenvalue_ratio, near_singular)

Bases: object

Numerical validation report for a covariance matrix.

Parameters:

• dimension (int)

• symmetric (bool)

• positive_definite (bool)

• effective_rank (int)

• eigenvalues (tuple[float, ...])

• eigenvalue_ratio (float)

• near_singular (bool)

dimension: int

symmetric: bool

positive_definite: bool

effective_rank: int

eigenvalues: tuple[float, ...]

eigenvalue_ratio: float

near_singular: bool

to_dict()

Return type:

dict[str, Any]

class pymixef.covariance.Diagonal(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Independent components parameterized by log standard deviations.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'diagonal'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.DiagonalCovariance

alias of Diagonal

class pymixef.covariance.HeterogeneousAR1(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

AR(1) correlation with one log standard deviation per position.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'heterogeneous-ar1'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, index=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• index (ArrayLike | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.HeterogeneousAR1Covariance

alias of HeterogeneousAR1

class pymixef.covariance.HeterogeneousToeplitz(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Toeplitz correlation with position-specific standard deviations.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'heterogeneous-toeplitz'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.HeterogeneousToeplitzCovariance

alias of HeterogeneousToeplitz

class pymixef.covariance.KnownCovariance(matrix, *, group=None)

Bases: CovarianceStructure

Fixed user-supplied covariance with no estimable parameters.

Parameters:

• matrix (ArrayLike)

• group (str | None)

name = 'known'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

covariance(parameters=(), *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

class pymixef.covariance.SpatialPower(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Spatial-power covariance sd² * rho**distance for arbitrary spacing.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'spatial-power'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, index=None, coordinates=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• index (ArrayLike | None)

• coordinates (ArrayLike | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.SpatialPowerCovariance

alias of SpatialPower

class pymixef.covariance.Toeplitz(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Stationary Toeplitz covariance using unconstrained partial correlations.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'toeplitz'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.ToeplitzCovariance

alias of Toeplitz

class pymixef.covariance.Unstructured(dimension=None, *, index=None, group=None)

Bases: CovarianceStructure

Unstructured SPD covariance parameterized by a Cholesky factor.

Parameters:

• dimension (int | None)

• index (str | None)

• group (str | None)

name = 'unstructured'

parameter_count(size=None)

Number of unconstrained parameters for a matrix dimension.

Parameters:

size (int | None)

Return type:

int

parameter_names(size=None)

Names matching the unconstrained parameter ordering.

Parameters:

size (int | None)

Return type:

tuple[str, …]

covariance(parameters, *, size=None, **_)

Construct the covariance matrix.

Parameters:

• parameters (ArrayLike)

• size (int | None)

• _ (Any)

Return type:

NDArray[float64]

pymixef.covariance.UnstructuredCovariance

alias of Unstructured

pymixef.covariance.covariance_structure(name, *args, **kwargs)

Construct a built-in or registered covariance structure by name.

Parameters:

• name (str)

• args (Any)

• kwargs (Any)

Return type:

CovarianceStructure

pymixef.covariance.get_covariance(name, *args, **kwargs)

Construct a built-in or registered covariance structure by name.

Parameters:

• name (str)

• args (Any)

• kwargs (Any)

Return type:

CovarianceStructure

pymixef.covariance.singularity_report(matrix, *, tolerance=1e-8)

Return non-raising rank, boundary, and near-perfect-correlation diagnostics.

Parameters:

• matrix (ArrayLike)

• tolerance (float)

Return type:

dict[str, Any]

pymixef.covariance.validate_covariance(matrix, *, positive_semidefinite=False, tolerance=1e-10)

Validate symmetry and definiteness and return numerical diagnostics.

Parameters:

• matrix (ArrayLike)

• positive_semidefinite (bool)

• tolerance (float)

Return type:

CovarianceValidation