class_docstr: 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 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
class_docstr_tok: ["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","can","not","be","instantiated","directly",".","Instead",",","use","one","of","the","factory","methods","(","e.g",".","`","Covariance.from_diagonal","`",")",".","Examples","--","--","--","--","The","`","Covariance","`","class","is","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"]
docstr: 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
docstr_tok: ["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"]
code: def from_precision(precision, covariance=None):
      r"""
      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
  
      """
      return CovViaPrecision(precision, covariance)
  
imports: from functools import cached_property
  import numpy
  from scipy import linalg
  from scipy.stats import _multivariate
label_desc: Use image node_id 3 for calling the Covariance obj's underlying member method code with example usage: obj.from_precision(precision, covariance) and returns: CovViaPrecision