Package com.irurueta.statistics

Class MultivariateNormalDist

java.lang.Object
com.irurueta.statistics.MultivariateNormalDist
public class MultivariateNormalDist extends Object
Contains methods to work with multivariate normal (i.e. Gaussian) distributions.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    MultivariateNormalDist.JacobianEvaluator
    Interface to evaluate a multivariate function at multivariate point x to obtain multivariate result y and its corresponding jacobian at point x.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private Matrix
    cov
    Covariance of Gaussian distribution.
    private Matrix
    covBasis
    Basis in which the covariance matrix is expressed.
    private double[]
    mu
    Mean value of Gaussian distribution.
    private double[]
    variances
    Variances on each direction of the basis.

  • Constructor Summary

    Constructors
    Constructor
    Description
    MultivariateNormalDist()
    Constructor.
    MultivariateNormalDist(double[] mean, Matrix covariance)
    Constructor.
    MultivariateNormalDist(double[] mean, Matrix covariance, boolean validateSymmetricPositiveDefinite)
    Constructor.
    MultivariateNormalDist(int dims)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    double
    cdf(double[] x)
    Evaluates the cumulative distribution function (c.d.f.) of a Gaussian distribution having current mean and covariance values.
    double
    cdf(double[] x, Matrix basis)
    Evaluates the cumulative distribution function (c.d.f.) of a Gaussian distribution having current mean and covariance values.
    Matrix
    getCovariance()
    Gets matrix containing covariance of this multivariate Gaussian distribution.
    void
    getCovariance(Matrix result)
    Gets matrix containing covariance of this multivariate Gaussian distribution.
    Matrix
    getCovarianceBasis()
    Basis containing on each column the direction of each variance in the multidimensional Gaussian distribution, which is obtained from provided covariance matrix.
    double[]
    getMean()
    Gets array containing mean of this multivariate Gaussian distribution.
    double[]
    getVariances()
    Array containing the amount of variance on each direction of the basis of the covariance in the multidimensional Gaussian distribution.
    double[]
    invcdf(double p)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value.
    double[]
    invcdf(double[] p)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
    void
    invcdf(double[] p, double[] result)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
    void
    invcdf(double[] p, double[] result, Matrix basis)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
    double[]
    invcdf(double[] p, Matrix basis)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
    void
    invcdf(double p, double[] result)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value.
    void
    invcdf(double p, double[] result, Matrix basis)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value.
    double[]
    invcdf(double p, Matrix basis)
    Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value.
    boolean
    isReady()
    Indicates whether this instance is ready for any computation, false otherwise.
    static boolean
    isValidCovariance(Matrix cov)
    Indicates whether provided matrix is a valid covariance matrix.
    static double
    jointProbability(double[] p)
    Computes the joint probability of all probabilities provided in the array.
    double
    mahalanobisDistance(double[] x)
    Computes the Mahalanobis distance of provided multivariate pot x for current mean and covariance values.
    double
    p(double[] x)
    Evaluates the probability density function (p.d.f.) of a multivariate Gaussian distribution having current mean and covariance at point x.
    void
    processCovariance()
    Processes current covariance by decomposing it into a basis and its corresponding variances if needed.
    static MultivariateNormalDist
    propagate(MultivariateNormalDist.JacobianEvaluator evaluator, double[] mean, Matrix covariance)
    Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    static void
    propagate(MultivariateNormalDist.JacobianEvaluator evaluator, double[] mean, Matrix covariance, MultivariateNormalDist result)
    Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    static MultivariateNormalDist
    propagate(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist dist)
    Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    static void
    propagate(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist dist, MultivariateNormalDist result)
    Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    MultivariateNormalDist
    propagateThisDistribution(MultivariateNormalDist.JacobianEvaluator evaluator)
    Evaluates the Jacobian and a multivariate function at the mean point of this distribution and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    void
    propagateThisDistribution(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist result)
    Evaluates the Jacobian and a multivariate function at the mean point of this distribution and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
    void
    setCovariance(Matrix cov)
    Sets covariance of this multivariate Gaussian distribution.
    void
    setCovariance(Matrix cov, boolean validateSymmetricPositiveDefinite)
    Sets covariance of this multivariate Gaussian distribution.
    void
    setMean(double[] mu)
    Sets mean of this multivariate Gaussian distribution.
    final void
    setMeanAndCovariance(double[] mu, Matrix cov)
    Sets mean and covariance of this multivariate Gaussian distribution.
    final void
    setMeanAndCovariance(double[] mu, Matrix cov, boolean validateSymmetricPositiveDefinite)
    Sets mean and covariance of this multivariate Gaussian distribution.
    double
    squaredMahalanobisDistance(double[] x)
    Computes the squared Mahalanobis distance of provided multivariate pot x for current mean and covariance values.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • mu

      private double[] mu
      Mean value of Gaussian distribution.

    • cov

      private Matrix cov
      Covariance of Gaussian distribution.

    • covBasis

      private Matrix covBasis
      Basis in which the covariance matrix is expressed. This value is obtained after decomposition.

    • variances

      private double[] variances
      Variances on each direction of the basis.

  • Constructor Details

    • MultivariateNormalDist

      public MultivariateNormalDist()
      Constructor. Creates a normal distribution of 1 dimension.

    • MultivariateNormalDist

      public MultivariateNormalDist(int dims)
      Constructor. Creates a multivariate normal distribution having the provided number of dimensions, with zero mean and unitary independent variances.
      Parameters:
      dims - number of dimensions. Must be greater than zero.
      Throws:
      IllegalArgumentException - if provided number of dimensions is zero or less.

    • MultivariateNormalDist

      public MultivariateNormalDist(double[] mean, Matrix covariance) throws InvalidCovarianceMatrixException
      Constructor. Creates a multivariate normal distribution having provided mean and covariance.
      Parameters:
      mean - array containing mean. Must have the same number of rows as provided covariance matrix
      covariance - matrix containing covariance. Must be square, symmetric and positive definite (i.e. non-singular) and must have the same number of rows as provided mean.
      Throws:
      IllegalArgumentException - if provided mean array has length smaller than 1 or if length of mean array is not the same as the number of rows of covariance matrix.
      InvalidCovarianceMatrixException - if provided covariance matrix is not square, symmetric and positive definite (i.e. non singular).

    • MultivariateNormalDist

      public MultivariateNormalDist(double[] mean, Matrix covariance, boolean validateSymmetricPositiveDefinite) throws InvalidCovarianceMatrixException
      Constructor. Creates a multivariate normal distribution having provided mean and covariance.
      Parameters:
      mean - array containing mean. Must have the same number of rows as provided covariance matrix.
      covariance - matrix containing covariance. Must be square, symmetric and positive definite (i.e. non-singular) and must have the same number of rows as provided mean.
      validateSymmetricPositiveDefinite - true if covariance matrix must be validated to be positive definite, false to skip validation.
      Throws:
      IllegalArgumentException - if provided mean array has length smaller than 1 or if length of mean array is not the same as the number of rows of covariance matrix.
      InvalidCovarianceMatrixException - if provided matrix is not valid (nor square or symmetric positive definite if validation is enabled).

  • Method Details

    • getMean

      public double[] getMean()
      Gets array containing mean of this multivariate Gaussian distribution.
      Returns:
      mean of multivariate Gaussian distribution.

    • setMean

      public void setMean(double[] mu)
      Sets mean of this multivariate Gaussian distribution. Length of provided mean must be equal to the number of rows of provided covariance, otherwise instance won't be ready.
      Parameters:
      mu - mean of multivariate Gaussian distribution.
      Throws:
      IllegalArgumentException - if provided array has a length smaller than 1.

    • getCovariance

      public Matrix getCovariance()
      Gets matrix containing covariance of this multivariate Gaussian distribution.
      Returns:
      covariance of multivariate Gaussian distribution.

    • getCovariance

      public void getCovariance(Matrix result)
      Gets matrix containing covariance of this multivariate Gaussian distribution.
      Parameters:
      result - instance where covariance of multivariate Gaussian distribution will be stored.

    • setCovariance

      public void setCovariance(Matrix cov) throws InvalidCovarianceMatrixException
      Sets covariance of this multivariate Gaussian distribution.
      Parameters:
      cov - covariance of this multivariate Gaussian distribution.
      Throws:
      InvalidCovarianceMatrixException - if provided matrix is not valid (not square or symmetric positive definite).

    • setCovariance

      public void setCovariance(Matrix cov, boolean validateSymmetricPositiveDefinite) throws InvalidCovarianceMatrixException
      Sets covariance of this multivariate Gaussian distribution.
      Parameters:
      cov - covariance of this multivariate Gaussian distribution.
      validateSymmetricPositiveDefinite - true if matrix must be validated to be positive definite, false to skip validation.
      Throws:
      InvalidCovarianceMatrixException - if provided matrix is not valid (nor square or symmetric positive definite if validation is enabled).

    • setMeanAndCovariance

      public final void setMeanAndCovariance(double[] mu, Matrix cov) throws InvalidCovarianceMatrixException
      Sets mean and covariance of this multivariate Gaussian distribution.
      Parameters:
      mu - array containing mean. Must have the same number of rows as provided covariance matrix
      cov - matrix containing covariance. Must be square, symmetric and positive definite (i.e. non-singular) and must have the same number of rows as provided mean.
      Throws:
      IllegalArgumentException - if provided mean array has length smaller than 1 or if length of mean array is not the same as the number of rows of covariance matrix.
      InvalidCovarianceMatrixException - if provided covariance matrix is not square, symmetric and positive definite (i.e. non singular).

    • setMeanAndCovariance

      public final void setMeanAndCovariance(double[] mu, Matrix cov, boolean validateSymmetricPositiveDefinite) throws InvalidCovarianceMatrixException
      Sets mean and covariance of this multivariate Gaussian distribution.
      Parameters:
      mu - array containing mean. Must have the same number of rows as provided covariance matrix
      cov - matrix containing covariance. Must be square, symmetric and positive definite (i.e. non-singular) and must have the same number of rows as provided mean.
      validateSymmetricPositiveDefinite - true if matrix must be validated to be positive definite, false to skip validation.
      Throws:
      IllegalArgumentException - if provided mean array has length smaller than 1 or if length of mean array is not the same as the number of rows of covariance matrix.
      InvalidCovarianceMatrixException - if provided covariance matrix is not square, symmetric and positive definite (i.e. non singular).

    • isValidCovariance

      public static boolean isValidCovariance(Matrix cov)
      Indicates whether provided matrix is a valid covariance matrix. A valid covariance matrix must be square, symmetric and positive definite (i.e. non-singular).
      Parameters:
      cov - matrix to be checked.
      Returns:
      true if matrix is a valid covariance matrix, false otherwise.

    • isReady

      public boolean isReady()
      Indicates whether this instance is ready for any computation, false otherwise.
      Returns:
      true if instance is ready, false otherwise.

    • getCovarianceBasis

      public Matrix getCovarianceBasis()
      Basis containing on each column the direction of each variance in the multidimensional Gaussian distribution, which is obtained from provided covariance matrix. This value is available only after the p.d.f. has been evaluated.
      Returns:
      basis containing on each column the direction of each variance in the multidimensional Gaussian distribution.

    • getVariances

      public double[] getVariances()
      Array containing the amount of variance on each direction of the basis of the covariance in the multidimensional Gaussian distribution. This value is available only after the p.d.f. has been evaluated.
      Returns:
      variance on each direction of the basis of the covariance.

    • p

      public double p(double[] x) throws NotReadyException, DecomposerException, RankDeficientMatrixException
      Evaluates the probability density function (p.d.f.) of a multivariate Gaussian distribution having current mean and covariance at point x.
      Parameters:
      x - array containing coordinates where p.d.f. is evaluated.
      Returns:
      evaluation of p.d.f.
      Throws:
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      IllegalArgumentException - if provided point length is not valid.
      DecomposerException - happens if covariance is numerically unstable (i.e. contains NaNs or very large numbers).
      RankDeficientMatrixException - happens if covariance is singular.

    • cdf

      public double cdf(double[] x, Matrix basis) throws NotReadyException, DecomposerException
      Evaluates the cumulative distribution function (c.d.f.) of a Gaussian distribution having current mean and covariance values. The c.d.f. is equivalent to the joint probability of the multivariate Gaussian distribution of having a value less than x on each direction of the basis of independent variances obtained from covariance matrix. Because the c.d.f is a probability, it always returns values between 0.0 and 1.0. NOTE: this method will resize provided basis instance if needed.
      Parameters:
      x - point where c.d.f. is evaluated.
      basis - instance where is stored the basis of each direction of independent covariances, if provided.
      Returns:
      evaluation of c.d.f.
      Throws:
      IllegalArgumentException - if length of provided point is not equal to length of current mean.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • cdf

      public double cdf(double[] x) throws NotReadyException, DecomposerException
      Evaluates the cumulative distribution function (c.d.f.) of a Gaussian distribution having current mean and covariance values. The c.d.f. is equivalent to the joint probability of the multivariate Gaussian distribution of having a value less than x on each direction of the basis of independent variances obtained from covariance matrix. Because the c.d.f is a probability, it always returns values between 0.0 and 1.0.
      Parameters:
      x - point where c.d.f. is evaluated.
      Returns:
      evaluation of c.d.f.
      Throws:
      IllegalArgumentException - if length of provided point is not equal to length of current mean.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • jointProbability

      public static double jointProbability(double[] p)
      Computes the joint probability of all probabilities provided in the array. The joint probability is computed by multiplying all components of the array, assuming that all probabilities are independent.
      Parameters:
      p - array containing probabilities for each independent variance direction that can be obtained from provided covariance matrix.
      Returns:
      joint probability.

    • invcdf

      public void invcdf(double[] p, double[] result, Matrix basis) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution. NOTE: this method will resize provided basis instance if needed.
      Parameters:
      p - array containing probability values to evaluate the inverse c.d.f. on each dimension. Values in the array must be between 0.0 and 1.0.
      result - coordinates of the value x for which the c.d.f. has values p.
      basis - instance where is stored the basis of each direction of independent covariances, if provided.
      Throws:
      IllegalArgumentException - if length of probabilities is not equal to mean length, or if result and length of probabilities are not equal, or if provided probabilities are not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public double[] invcdf(double[] p, Matrix basis) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution. NOTE: this method will resize provided basis instance if needed.
      Parameters:
      p - array containing probability values to evaluate the inverse c.d.f. on each dimension. Values in the array must be between 0.0 and 1.0.
      basis - instance where is stored the basis of each direction of independent covariances, if provided.
      Returns:
      a new array containing coordinates of the value x for which the c.d.f. has values p.
      Throws:
      IllegalArgumentException - if length of probabilities is not equal to mean length, or if provided probabilities are not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public void invcdf(double[] p, double[] result) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
      Parameters:
      p - array containing probability values to evaluate the inverse c.d.f. on each dimension. Values in the array must be between 0.0 and 1.0.
      result - coordinates of the value x for which the c.d.f. has values p.
      Throws:
      IllegalArgumentException - if length of probabilities is not equal to mean length, or if result and length of probabilities are not equal, or if provided probabilities are not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public double[] invcdf(double[] p) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability values for each dimension of the multivariate Gaussian distribution.
      Parameters:
      p - array containing probability values to evaluate the inverse c.d.f. on each dimension. Values in the array must be between 0.0 and 1.0.
      Returns:
      coordinates of the value x for which the c.d.f. has values * p.
      Throws:
      IllegalArgumentException - if length of probabilities is not equal to mean length, or if result and length of probabilities are not equal, or if provided probabilities are not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public void invcdf(double p, double[] result, Matrix basis) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value. Obtained result coordinates are computed taking into account the basis of independent variances computed from current covariance matrix. NOTE: notice that the inverse cdf of a mutivariate Gaussian distribution does not have a unique solution. This method simply returns one of the possible solutions by assuming equal probabilities on each dimension. NOTE: this method will resize provided basis instance if needed.
      Parameters:
      p - probability value to evaluate the inverse c.d.f. at. This value must be between 0.0 and 1.0
      result - coordinates of the value x for which the c.d.f. has value p.
      basis - instance where is stored the basis of each direction of independent covariances, if provided.
      Throws:
      IllegalArgumentException - if provided probability value is not between 0.0 and 1.0, if length of provided result array is not equal to length of current mean.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - if covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public double[] invcdf(double p, Matrix basis) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value. Obtained result coordinates are computed taking into account the basis of independent variances computed from current covariance matrix. NOTE: notice that the inverse cdf of a mutivariate Gaussian distribution does not have a unique solution. This method simply returns one of the possible solutions by assuming equal probabilities on each dimension. NOTE: this method will resize provided basis instance if needed.
      Parameters:
      p - probability value to evaluate the inverse c.d.f. at. This value must be between 0.0 and 1.0
      basis - instance where is stored the basis of each direction of independent covariances, if provided.
      Returns:
      a new array containing the coordinates of the value x for which the c.d.f. has value p.
      Throws:
      IllegalArgumentException - if provided probability value is not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - f covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public void invcdf(double p, double[] result) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value. Obtained result coordinates are computed taking into account the basis of independent variances computed from current covariance matrix. NOTE: notice that the inverse cdf of a mutivariate Gaussian distribution does not have a unique solution. This method simply returns one of the possible solutions by assuming equal probabilities on each dimension.
      Parameters:
      p - probability value to evaluate the inverse c.d.f. at. This value must be between 0.0 and 1.0
      result - coordinates of the value x for which the c.d.f. has value p.
      Throws:
      IllegalArgumentException - if provided probability value is not between 0.0 and 1.0, if length of provided result array is not equal to length of current mean.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - f covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • invcdf

      public double[] invcdf(double p) throws NotReadyException, DecomposerException
      Evaluates the inverse cumulative distribution function of a multivariate Gaussian distribution for current mean and covariance values and provided probability value. Obtained result coordinates are computed taking into account the basis of independent variances computed from current covariance matrix. NOTE: notice that the inverse cdf of a mutivariate Gaussian distribution does not have a unique solution. This method simply returns one of the possible solutions by assuming equal probabilities on each dimension.
      Parameters:
      p - probability value to evaluate the inverse c.d.f. at. This value must be between 0.0 and 1.0
      Returns:
      a new array containing the coordinates of the value x for which the c.d.f. has value p.
      Throws:
      IllegalArgumentException - if provided probability value is not between 0.0 and 1.0.
      NotReadyException - if this instance is not ready (mean and covariance have not been provided or are not valid).
      DecomposerException - f covariance is numerically unstable (i.e. contains NaNs or very large numbers).

    • mahalanobisDistance

      public double mahalanobisDistance(double[] x) throws DecomposerException, RankDeficientMatrixException
      Computes the Mahalanobis distance of provided multivariate pot x for current mean and covariance values.
      Parameters:
      x - point where Mahalanobis distance is evaluated.
      Returns:
      Mahalanobis distance of provided point respect to mean.
      Throws:
      DecomposerException - happens if covariance is numerically unstable (i.e. contains NaNs or very large numbers).
      RankDeficientMatrixException - happens if covariance is singular.

    • squaredMahalanobisDistance

      public double squaredMahalanobisDistance(double[] x) throws DecomposerException, RankDeficientMatrixException
      Computes the squared Mahalanobis distance of provided multivariate pot x for current mean and covariance values.
      Parameters:
      x - point where Mahalanobis distance is evaluated.
      Returns:
      Mahalanobis distance of provided point respect to mean.
      Throws:
      DecomposerException - happens if covariance is numerically unstable (i.e. contains NaNs or very large numbers).
      RankDeficientMatrixException - happens if covariance is singular.

    • processCovariance

      public void processCovariance() throws DecomposerException, NotReadyException, LockedException, NotAvailableException
      Processes current covariance by decomposing it into a basis and its corresponding variances if needed.
      Throws:
      DecomposerException - happens if covariance is numerically unstable (i.e. contains NaNs or very large numbers).
      NotReadyException - never thrown because decomposer will always be ready.
      LockedException - never thrown because decomposer will never be locked.
      NotAvailableException - never thrown because first a DecomposerException will be thrown before attempting to get V or singular values.

    • propagate

      public static void propagate(MultivariateNormalDist.JacobianEvaluator evaluator, double[] mean, Matrix covariance, MultivariateNormalDist result) throws WrongSizeException, InvalidCovarianceMatrixException
      Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      mean - mean of original multivariate Gaussian distribution to be propagated. Must have the length of the number of input variables of the multivariate function to be evaluated.
      covariance - covariance of original Gaussian distribution to be propagated. Must be symmetric positive definite having size NxN where N is the length of provided mean.
      result - instance where propagated multiavariate Gaussian distribution will be stored.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      InvalidCovarianceMatrixException - if provided covariance matrix is not valid (i.e. is not symmetric positive definite).
      See Also:

    • propagate

      public static MultivariateNormalDist propagate(MultivariateNormalDist.JacobianEvaluator evaluator, double[] mean, Matrix covariance) throws WrongSizeException, InvalidCovarianceMatrixException
      Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      mean - mean of original multivariate Gaussian distribution to be propagated. Must have the length of the number of input variables of the multivariate function to be evaluated.
      covariance - covariance of original Gaussian distribution to be propagated. Must be symmetric positive definite having size NxN where N is the length of provided mean.
      Returns:
      a new propagated multivariate Gaussian distribution.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      InvalidCovarianceMatrixException - if provided covariance matrix is not valid (i.e. is not symmetric positive definite).
      See Also:

    • propagate

      public static void propagate(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist dist, MultivariateNormalDist result) throws WrongSizeException
      Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      dist - multivariate Gaussian distribution to be propagated.
      result - instance where propagated multivariate Gaussian distribution will be stored.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      See Also:

    • propagate

      public static MultivariateNormalDist propagate(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist dist) throws WrongSizeException
      Evaluates the Jacobian and a multivariate function at a certain mean point and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      dist - multivariate Gaussian distribution to be propagated.
      Returns:
      a new propagated multivariate Gaussian distribution.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      See Also:

    • propagateThisDistribution

      public void propagateThisDistribution(MultivariateNormalDist.JacobianEvaluator evaluator, MultivariateNormalDist result) throws WrongSizeException
      Evaluates the Jacobian and a multivariate function at the mean point of this distribution and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      result - instance where propagated multivariate Gaussian distribution will be stored.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      See Also:

    • propagateThisDistribution

      public MultivariateNormalDist propagateThisDistribution(MultivariateNormalDist.JacobianEvaluator evaluator) throws WrongSizeException
      Evaluates the Jacobian and a multivariate function at the mean point of this distribution and computes the non-linear propagation of Gaussian uncertainty through such function at such point.
      Parameters:
      evaluator - interface to evaluate a multivariate function and its Jacobian at a certain point.
      Returns:
      a new propagated multivariate Gaussian distribution.
      Throws:
      WrongSizeException - if evaluator returns an invalid number of variables (i.e. negative or zero).
      See Also: