(phWSSKJr SSKrSSKJr SSKJr S/r"SS5r "SS\ 5r S r "S S \ 5r "S S \ 5r "SS\ 5r"SS\ 5rg))cached_propertyN)linalg) _multivariate Covariancec\rSrSrSrSr\S5r\SSj5r\S5r \S5r S r S r \ S 5r\ S 5r\ S 5r\ S5rSrSrSrg)r a Representation of a covariance matrix Calculations involving covariance matrices (e.g. data whitening, multivariate normal function evaluation) are often performed more efficiently using a decomposition of the covariance matrix instead of the covariance matrix itself. This class allows the user to construct an object representing a covariance matrix using any of several decompositions and perform calculations using a common interface. .. note:: The `Covariance` class cannot be instantiated directly. Instead, use one of the factory methods (e.g. `Covariance.from_diagonal`). Examples -------- The `Covariance` class is used by calling one of its factory methods to create a `Covariance` object, then pass that representation of the `Covariance` matrix as a shape parameter of a multivariate distribution. For instance, the multivariate normal distribution can accept an array representing a covariance matrix: >>> from scipy import stats >>> import numpy as np >>> d = [1, 2, 3] >>> A = np.diag(d) # a diagonal covariance matrix >>> x = [4, -2, 5] # a point of interest >>> dist = stats.multivariate_normal(mean=[0, 0, 0], cov=A) >>> dist.pdf(x) 4.9595685102808205e-08 but the calculations are performed in a very generic way that does not take advantage of any special properties of the covariance matrix. Because our covariance matrix is diagonal, we can use ``Covariance.from_diagonal`` to create an object representing the covariance matrix, and `multivariate_normal` can use this to compute the probability density function more efficiently. >>> cov = stats.Covariance.from_diagonal(d) >>> dist = stats.multivariate_normal(mean=[0, 0, 0], cov=cov) >>> dist.pdf(x) 4.9595685102808205e-08 cSn[U5e)NzThe `Covariance` class cannot be instantiated directly. Please use one of the factory methods (e.g. `Covariance.from_diagonal`).)NotImplementedError)selfmessages J/var/www/html/venv/lib/python3.13/site-packages/scipy/stats/_covariance.py__init__Covariance.__init__;s8"'**c[U5$)ae Return a representation of a covariance matrix from its diagonal. Parameters ---------- diagonal : array_like The diagonal elements of a diagonal matrix. Notes ----- Let the diagonal elements of a diagonal covariance matrix :math:`D` be stored in the vector :math:`d`. When all elements of :math:`d` are strictly positive, whitening of a data point :math:`x` is performed by computing :math:`x \cdot d^{-1/2}`, where the inverse square root can be taken element-wise. :math:`\log\det{D}` is calculated as :math:`-2 \sum(\log{d})`, where the :math:`\log` operation is performed element-wise. This `Covariance` class supports singular covariance matrices. When computing ``_log_pdet``, non-positive elements of :math:`d` are ignored. Whitening is not well defined when the point to be whitened does not lie in the span of the columns of the covariance matrix. The convention taken here is to treat the inverse square root of non-positive elements of :math:`d` as zeros. Examples -------- Prepare a symmetric positive definite covariance matrix ``A`` and a data point ``x``. >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng() >>> n = 5 >>> A = np.diag(rng.random(n)) >>> x = rng.random(size=n) Extract the diagonal from ``A`` and create the `Covariance` object. >>> d = np.diag(A) >>> cov = stats.Covariance.from_diagonal(d) Compare the functionality of the `Covariance` object against a reference implementations. >>> res = cov.whiten(x) >>> ref = np.diag(d**-0.5) @ x >>> np.allclose(res, ref) True >>> res = cov.log_pdet >>> ref = np.linalg.slogdet(A)[-1] >>> np.allclose(res, ref) True )CovViaDiagonal)diagonals r from_diagonalCovariance.from_diagonalAsvh''rNc[X5$)a Return a representation of a covariance from its precision matrix. Parameters ---------- precision : array_like The precision matrix; that is, the inverse of a square, symmetric, positive definite covariance matrix. covariance : array_like, optional The square, symmetric, positive definite covariance matrix. If not provided, this may need to be calculated (e.g. to evaluate the cumulative distribution function of `scipy.stats.multivariate_normal`) by inverting `precision`. Notes ----- Let the covariance matrix be :math:`A`, its precision matrix be :math:`P = A^{-1}`, and :math:`L` be the lower Cholesky factor such that :math:`L L^T = P`. Whitening of a data point :math:`x` is performed by computing :math:`x^T L`. :math:`\log\det{A}` is calculated as :math:`-2tr(\log{L})`, where the :math:`\log` operation is performed element-wise. This `Covariance` class does not support singular covariance matrices because the precision matrix does not exist for a singular covariance matrix. Examples -------- Prepare a symmetric positive definite precision matrix ``P`` and a data point ``x``. (If the precision matrix is not already available, consider the other factory methods of the `Covariance` class.) >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng() >>> n = 5 >>> P = rng.random(size=(n, n)) >>> P = P @ P.T # a precision matrix must be positive definite >>> x = rng.random(size=n) Create the `Covariance` object. >>> cov = stats.Covariance.from_precision(P) Compare the functionality of the `Covariance` object against reference implementations. >>> res = cov.whiten(x) >>> ref = x @ np.linalg.cholesky(P) >>> np.allclose(res, ref) True >>> res = cov.log_pdet >>> ref = -np.linalg.slogdet(P)[-1] >>> np.allclose(res, ref) True )CovViaPrecision) precision covariances r from_precisionCovariance.from_precision~szy55rc[U5$)a Representation of a covariance provided via the (lower) Cholesky factor Parameters ---------- cholesky : array_like The lower triangular Cholesky factor of the covariance matrix. Notes ----- Let the covariance matrix be :math:`A` and :math:`L` be the lower Cholesky factor such that :math:`L L^T = A`. Whitening of a data point :math:`x` is performed by computing :math:`L^{-1} x`. :math:`\log\det{A}` is calculated as :math:`2tr(\log{L})`, where the :math:`\log` operation is performed element-wise. This `Covariance` class does not support singular covariance matrices because the Cholesky decomposition does not exist for a singular covariance matrix. Examples -------- Prepare a symmetric positive definite covariance matrix ``A`` and a data point ``x``. >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng() >>> n = 5 >>> A = rng.random(size=(n, n)) >>> A = A @ A.T # make the covariance symmetric positive definite >>> x = rng.random(size=n) Perform the Cholesky decomposition of ``A`` and create the `Covariance` object. >>> L = np.linalg.cholesky(A) >>> cov = stats.Covariance.from_cholesky(L) Compare the functionality of the `Covariance` object against reference implementation. >>> from scipy.linalg import solve_triangular >>> res = cov.whiten(x) >>> ref = solve_triangular(L, x, lower=True) >>> np.allclose(res, ref) True >>> res = cov.log_pdet >>> ref = np.linalg.slogdet(A)[-1] >>> np.allclose(res, ref) True )CovViaCholesky)choleskys r from_choleskyCovariance.from_choleskysph''rc[U5$)aZ Representation of a covariance provided via eigendecomposition Parameters ---------- eigendecomposition : sequence A sequence (nominally a tuple) containing the eigenvalue and eigenvector arrays as computed by `scipy.linalg.eigh` or `numpy.linalg.eigh`. Notes ----- Let the covariance matrix be :math:`A`, let :math:`V` be matrix of eigenvectors, and let :math:`W` be the diagonal matrix of eigenvalues such that `V W V^T = A`. When all of the eigenvalues are strictly positive, whitening of a data point :math:`x` is performed by computing :math:`x^T (V W^{-1/2})`, where the inverse square root can be taken element-wise. :math:`\log\det{A}` is calculated as :math:`tr(\log{W})`, where the :math:`\log` operation is performed element-wise. This `Covariance` class supports singular covariance matrices. When computing ``_log_pdet``, non-positive eigenvalues are ignored. Whitening is not well defined when the point to be whitened does not lie in the span of the columns of the covariance matrix. The convention taken here is to treat the inverse square root of non-positive eigenvalues as zeros. Examples -------- Prepare a symmetric positive definite covariance matrix ``A`` and a data point ``x``. >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng() >>> n = 5 >>> A = rng.random(size=(n, n)) >>> A = A @ A.T # make the covariance symmetric positive definite >>> x = rng.random(size=n) Perform the eigendecomposition of ``A`` and create the `Covariance` object. >>> w, v = np.linalg.eigh(A) >>> cov = stats.Covariance.from_eigendecomposition((w, v)) Compare the functionality of the `Covariance` object against reference implementations. >>> res = cov.whiten(x) >>> ref = x @ (v @ np.diag(w**-0.5)) >>> np.allclose(res, ref) True >>> res = cov.log_pdet >>> ref = np.linalg.slogdet(A)[-1] >>> np.allclose(res, ref) True )CovViaEigendecomposition)eigendecompositions r from_eigendecomposition"Covariance.from_eigendecompositions@((:;;rcLUR[R"U55$)ai Perform a whitening transformation on data. "Whitening" ("white" as in "white noise", in which each frequency has equal magnitude) transforms a set of random variables into a new set of random variables with unit-diagonal covariance. When a whitening transform is applied to a sample of points distributed according to a multivariate normal distribution with zero mean, the covariance of the transformed sample is approximately the identity matrix. Parameters ---------- x : array_like An array of points. The last dimension must correspond with the dimensionality of the space, i.e., the number of columns in the covariance matrix. Returns ------- x_ : array_like The transformed array of points. References ---------- .. [1] "Whitening Transformation". Wikipedia. https://en.wikipedia.org/wiki/Whitening_transformation .. [2] Novak, Lukas, and Miroslav Vorechovsky. "Generalization of coloring linear transformation". Transactions of VSB 18.2 (2018): 31-35. :doi:`10.31490/tces-2018-0013` Examples -------- >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng() >>> n = 3 >>> A = rng.random(size=(n, n)) >>> cov_array = A @ A.T # make matrix symmetric positive definite >>> precision = np.linalg.inv(cov_array) >>> cov_object = stats.Covariance.from_precision(precision) >>> x = rng.multivariate_normal(np.zeros(n), cov_array, size=(10000)) >>> x_ = cov_object.whiten(x) >>> np.cov(x_, rowvar=False) # near-identity covariance array([[0.97862122, 0.00893147, 0.02430451], [0.00893147, 0.96719062, 0.02201312], [0.02430451, 0.02201312, 0.99206881]]) )_whitennpasarrayr xs r whitenCovariance.whiten9sb||BJJqM**rcLUR[R"U55$)a Perform a colorizing transformation on data. "Colorizing" ("color" as in "colored noise", in which different frequencies may have different magnitudes) transforms a set of uncorrelated random variables into a new set of random variables with the desired covariance. When a coloring transform is applied to a sample of points distributed according to a multivariate normal distribution with identity covariance and zero mean, the covariance of the transformed sample is approximately the covariance matrix used in the coloring transform. Parameters ---------- x : array_like An array of points. The last dimension must correspond with the dimensionality of the space, i.e., the number of columns in the covariance matrix. Returns ------- x_ : array_like The transformed array of points. References ---------- .. [1] "Whitening Transformation". Wikipedia. https://en.wikipedia.org/wiki/Whitening_transformation .. [2] Novak, Lukas, and Miroslav Vorechovsky. "Generalization of coloring linear transformation". Transactions of VSB 18.2 (2018): 31-35. :doi:`10.31490/tces-2018-0013` Examples -------- >>> import numpy as np >>> from scipy import stats >>> rng = np.random.default_rng(1638083107694713882823079058616272161) >>> n = 3 >>> A = rng.random(size=(n, n)) >>> cov_array = A @ A.T # make matrix symmetric positive definite >>> cholesky = np.linalg.cholesky(cov_array) >>> cov_object = stats.Covariance.from_cholesky(cholesky) >>> x = rng.multivariate_normal(np.zeros(n), np.eye(n), size=(10000)) >>> x_ = cov_object.colorize(x) >>> cov_data = np.cov(x_, rowvar=False) >>> np.allclose(cov_data, cov_array, rtol=3e-2) True ) _colorizer(r)r*s r colorizeCovariance.colorizelsb~~bjjm,,rcN[R"UR[S9S$)z8 Log of the pseudo-determinant of the covariance matrix dtype)r(array _log_pdetfloatr s r log_pdetCovariance.log_pdets xxe4R88rcN[R"UR[S9S$)z Rank of the covariance matrix r3r5)r(r6_rankintr9s r rankCovariance.ranks xx #.r22rcUR$)z2 Explicit representation of the covariance matrix ) _covariancer9s r rCovariance.covariances rcUR$)z Shape of the covariance array )_shaper9s r shapeCovariance.shapes {{rcp[R"U5nURSSup4X4:wdxURS:wdh[R"UR [R 5(dE[R"UR [R5(dSUS3n[U5eU$)N The input `z:` must be a square, two-dimensional array of real numbers.) r( atleast_2drFndim issubdtyper4integerfloating ValueError)r Anamemnr s r _validate_matrixCovariance._validate_matrixs MM! wwrs| 6QVVq[qww )K)K)+qww )L)L$TF+@@GW% %rcD[R"U5nURS:wdh[R"UR[R 5(dE[R"UR[R 5(dSUS3n[U5eU$)NrKz2` must be a one-dimensional array of real numbers.)r( atleast_1drMrNr4rOrPrQ)r rRrSr s r _validate_vectorCovariance._validate_vectorso MM!  66Q;r}}QWWbjjAA!}}QWWbkkBB$TF+**GW% %rr5N)__name__ __module__ __qualname____firstlineno____doc__r staticmethodrrrr$r,r0propertyr:r?rrFrVr[__static_attributes__r5rr rr s.^+ :(:(x<6<6|7(7(r?<?QHHXRZZ@$%!'8 9C):!;;%&" ggh/%&,,R06::2:3FF ..rwwHE &&,, #rc,[XR5$r])rrr*s r r'CovViaDiagonal._whiten sHH%%rc,[XR5$r])rrr*s r r/CovViaDiagonal._colorizes//00rcT[R"[XR5SS9)$z: Check whether x lies in the support of the distribution. rhri)r(anyrrr*s r _support_maskCovViaDiagonal._support_masks!yLL1;;;r)rrqrBrr7r=rErN) r^r_r`rarr'r/rrer5rr rrs$(&1>!!r)rqrr7r=rEN) r^r_r`rarrrBr'r/rer5rr rrs%%--"rrc<\rSrSrSrSrSr\S5rSr Sr g) r"i/cUup#URUS5nURUS5nSn[R"US5n[R"UU5up2USSSS24nUS:*n[R "U[RS9nSXe'[R"[R"U5S S 9Ul S[R"U5- nSXu'X7-Ul U[R"U5-Ul URS URS S 9- UlX lX0lURUlX5-Ul[(R*"U5S -UlS Ulg![ a [ U5ef=f) N eigenvalues eigenvectorszBThe shapes of `eigenvalues` and `eigenvectors` must be compatible.rI.rr3rYrhriiT)r[rVr(rbroadcast_arraysrQr6rrnrlr7rr_LArFr=_w_vrE _null_basisr_eigvalsh_to_eps_epsrq)r r#rrr rpositive_eigenvaluesrs r r!CovViaEigendecomposition.__init__1sw$6! ++KG ,,\>J ) &..b9K(*(;(;L>%&"4"''+"66)//3fjjbj6II "(( '0"22;?%G #- &W% % &s :E44F cXR-$r]rr*s r r' CovViaEigendecomposition._whitenT88|rc2XRR-$r])rr}r*s r r/"CovViaEigendecomposition._colorizeWs88::~rcbURUR-URR-$r])rrr}r9s r rB$CovViaEigendecomposition._covarianceZs"$''!TWWYY..rcv[RRXR-SS9nX R:nU$r)r(rnormrr)r r+residual in_supports r r&CovViaEigendecomposition._support_mask^s599>>!&6&6"6R>@ ) r) rrrqrr7rr=rErrN) r^r_r`rarr'r/rrBrrer5rr r"r"/s+!$F//rr"c*\rSrSrSrSrSrSrSrg) CovViaPSDigzA Representation of a covariance provided via an instance of _PSD cURUlURUlURUlUR UlUR RUl Xl SUl g)NF) Urr:r7r?r=_MrBrFrE_psdrq)r psds r rCovViaPSD.__init__lsK55XX 66ffll  $rcXR-$r]rr*s r r'CovViaPSD._whitenurrc8URRU5$r])rrr*s r rCovViaPSD._support_maskxsyy&&q))r)rrqrBr7rr=rEN) r^r_r`rarbrr'rrer5rr rrgs%*rr) functoolsrnumpyr(scipyr scipy.statsr__all__rrrrrr"rr5rr rsl%% .AAHKjK>>