MultivariateGaussian (Cognitive Foundry)

java.lang.Object
- gov.sandia.cognition.util.AbstractCloneableSerializable
- - gov.sandia.cognition.statistics.AbstractDistribution<Vector>
  - - gov.sandia.cognition.statistics.distribution.MultivariateGaussian

All Implemented Interfaces:: Vectorizable, ClosedFormComputableDistribution<Vector>, ClosedFormDistribution<Vector>, ComputableDistribution<Vector>, Distribution<Vector>, DistributionWithMean<Vector>, EstimableDistribution<Vector,MultivariateGaussian>, CloneableSerializable, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:: MultivariateGaussian.PDF

@CodeReview(reviewer="Jonathan McClain",
            date="2006-05-15",
            changesNeeded=true,
            comments={"A few minor changes needed.","Comments indicated with a / / / comment in the first column."},
            response=@CodeReviewResponse(respondent="Kevin R. Dixon",date="2006-05-15",moreChangesNeeded=false,comments="Fixed."))
 @PublicationReference(author="Wikipedia",
                      title="Multivariate normal distribution",
                      type=WebPage,
                      year=2009,
                      url="http://en.wikipedia.org/wiki/Multivariate_normal_distribution")
public class MultivariateGaussian
extends AbstractDistribution<Vector>
implements ClosedFormComputableDistribution<Vector>, EstimableDistribution<Vector,MultivariateGaussian>

The MultivariateGaussian class implements a multidimensional Gaussian distribution that contains a mean vector and a covariance matrix. If your underlying distribution is univariate (scalar), then use the UnivariateGaussian class, as its operations are MUCH less computationally intensive.

Since:: 1.0
Author:: Justin Basilico, Kevin R. Dixon
See Also:: Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`MultivariateGaussian.IncrementalEstimator` The estimator that creates a MultivariateGaussian from a stream of values.
`static class`	`MultivariateGaussian.IncrementalEstimatorCovarianceInverse` The estimator that creates a MultivariateGaussian from a stream of values by estimating the mean and covariance inverse (as opposed to the covariance directly), without ever performing a matrix inversion.
`static class`	`MultivariateGaussian.MaximumLikelihoodEstimator` Computes the Maximum Likelihood Estimate of the MultivariateGaussian given a set of Vectors
`static class`	`MultivariateGaussian.PDF` PDF of a multivariate Gaussian
`static class`	`MultivariateGaussian.SufficientStatistic` Implements the sufficient statistics of the MultivariateGaussian.
`static class`	`MultivariateGaussian.SufficientStatisticCovarianceInverse` Implements the sufficient statistics of the MultivariateGaussian while estimating the inverse of the covariance matrix.
`static class`	`MultivariateGaussian.WeightedMaximumLikelihoodEstimator` Computes the Weighted Maximum Likelihood Estimate of the MultivariateGaussian given a weighted set of Vectors

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`DEFAULT_COVARIANCE_SYMMETRY_TOLERANCE` Tolerance check for symmetry covariance tolerance, 1.0E-5.
`static int`	`DEFAULT_DIMENSIONALITY` Default dimensionality of the Gaussian, 2
`static double`	`LOG_TWO_PI` Natural logarithm of 2pi.

Constructor Summary

Constructors
Constructor and Description
`MultivariateGaussian()` Default constructor.
`MultivariateGaussian(int dimensionality)` Creates a new instance of MultivariateGaussian.
`MultivariateGaussian(MultivariateGaussian other)` Creates a new instance of MultivariateGaussian.
`MultivariateGaussian(Vector mean, Matrix covariance)` Creates a new instance of MultivariateGaussian.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`MultivariateGaussian`	`clone()` This makes public the clone method on the `Object` class and removes the exception that it throws.
`double`	`computeZSquared(Vector input)` Computes the z value squared, such that p(x) = coefficient * exp{-0.5*z^2}
`void`	`convertFromVector(Vector parameters)` Converts the object from a Vector of parameters.
`Vector`	`convertToVector()` Converts the object to a vector.
`MultivariateGaussian`	`convolve(MultivariateGaussian other)` Convolves this Gaussian with the other Gaussian.
`boolean`	`equals(java.lang.Object randomVariable)`
`Matrix`	`getCovariance()` Gets the covariance matrix of the Gaussian.
`Matrix`	`getCovarianceInverse()` Gets the inverse of the covariance matrix.
`MultivariateGaussian.MaximumLikelihoodEstimator`	`getEstimator()` Gets an estimator associated with this distribution.
`int`	`getInputDimensionality()` Gets the dimensionality of the Gaussian.
`double`	`getLogCovarianceDeterminant()` Getter for logCovarianceDeterminant
`double`	`getLogLeadingCoefficient()` Getter for logLeadingCoefficient
`Vector`	`getMean()` Gets the arithmetic mean, or "first central moment" or "expectation", of the distribution.
`MultivariateGaussian.PDF`	`getProbabilityFunction()` Gets the distribution function associated with this Distribution, either the PDF or PMF.
`int`	`hashCode()`
`MultivariateGaussian`	`plus(MultivariateGaussian other)` Adds two MultivariateGaussian random variables together and returns the resulting MultivariateGaussian
`static Vector`	`sample(Vector mean, Matrix covarianceSquareRoot, java.util.Random random)` Returns a single draw from the Gaussian with the given mean and covariance.
`static java.util.ArrayList<Vector>`	`sample(Vector mean, Matrix covarianceSquareRoot, java.util.Random random, int sampleCount)` Returns a collection of draws this Gaussian with the given mean and covariance.
`void`	`sampleInto(java.util.Random random, int sampleCount, java.util.Collection<? super Vector> output)` Draws multiple random samples from the distribution and puts the result into the given collection.
`static void`	`sampleInto(Vector mean, Matrix covarianceSquareRoot, java.util.Random random, int sampleCount, java.util.Collection<? super Vector> output)` Performs a collection of draws this Gaussian with the given mean and covariance.
`MultivariateGaussian`	`scale(Matrix premultiplyMatrix)` Scales the MultivariateGaussian by premultiplying by the given Matrix
`void`	`setCovariance(Matrix covariance)` Sets the covariance matrix.
`void`	`setCovariance(Matrix covariance, double symmetryTolerance)` Sets the covariance matrix.
`void`	`setCovarianceInverse(Matrix covarianceInverse)` Sets the covariance inverse
`void`	`setCovarianceInverse(Matrix covarianceInverse, double symmetryTolerance)` Sets the covariance inverse
`void`	`setMean(Vector mean)` Sets the mean vector.
`MultivariateGaussian`	`times(MultivariateGaussian other)` Multiplies this Gaussian with the other Gaussian.
`java.lang.String`	`toString()`

Methods inherited from class gov.sandia.cognition.statistics.AbstractDistribution
sample, sample

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface gov.sandia.cognition.statistics.Distribution
sample, sample

- Field Detail
  - DEFAULT_COVARIANCE_SYMMETRY_TOLERANCE
```
public static final double DEFAULT_COVARIANCE_SYMMETRY_TOLERANCE
```
    Tolerance check for symmetry covariance tolerance, 1.0E-5.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_DIMENSIONALITY
```
public static final int DEFAULT_DIMENSIONALITY
```
    Default dimensionality of the Gaussian, 2
    
    See Also:
    
    Constant Field Values
  - LOG_TWO_PI
```
public static final double LOG_TWO_PI
```
    Natural logarithm of 2pi.
- Constructor Detail
  - MultivariateGaussian
```
public MultivariateGaussian()
```
    Default constructor.
  - MultivariateGaussian
```
public MultivariateGaussian(int dimensionality)
```
    Creates a new instance of MultivariateGaussian.
    
    Parameters:
    
    dimensionality - Dimensionality of the Gaussian to create.
  - MultivariateGaussian
```
public MultivariateGaussian(Vector mean,
                            Matrix covariance)
```
    Creates a new instance of MultivariateGaussian.
    
    Parameters:
    
    mean - The mean of the Gaussian distribution.
    
    covariance - The covariance matrix, which should be a symmetric matrix.
  - MultivariateGaussian
```
public MultivariateGaussian(MultivariateGaussian other)
```
    Creates a new instance of MultivariateGaussian.
    
    Parameters:
    
    other - The other MultivariateGaussian to copy.
- Method Detail
  - clone
```
public MultivariateGaussian clone()
```
    Description copied from class: AbstractCloneableSerializable
    
    This makes public the clone method on the Object class and removes the exception that it throws. Its default behavior is to automatically create a clone of the exact type of object that the clone is called on and to copy all primitives but to keep all references, which means it is a shallow copy. Extensions of this class may want to override this method (but call super.clone() to implement a "smart copy". That is, to target the most common use case for creating a copy of the object. Because of the default behavior being a shallow copy, extending classes only need to handle fields that need to have a deeper copy (or those that need to be reset). Some of the methods in ObjectUtil may be helpful in implementing a custom clone method. Note: The contract of this method is that you must use super.clone() as the basis for your implementation.
    
    Specified by:
    
    clone in interface Vectorizable
    
    Specified by:
    
    clone in interface CloneableSerializable
    
    Overrides:
    
    clone in class AbstractCloneableSerializable
    
    Returns:
    
    A clone of this object.
  - getProbabilityFunction
```
public MultivariateGaussian.PDF getProbabilityFunction()
```
    Description copied from interface: ComputableDistribution
    
    Gets the distribution function associated with this Distribution, either the PDF or PMF.
    
    Specified by:
    
    getProbabilityFunction in interface ComputableDistribution<Vector>
    
    Returns:
    
    Distribution function associated with this Distribution.
  - computeZSquared
```
public double computeZSquared(Vector input)
```
    Computes the z value squared, such that p(x) = coefficient * exp{-0.5*z^2}
    
    Parameters:
    
    input - input about which to compute the z-value squared
    
    Returns:
    
    z-value squared
  - times
```
public MultivariateGaussian times(MultivariateGaussian other)
```
    Multiplies this Gaussian with the other Gaussian. This is also equivalent to computing the posterior belief using one of the Gaussians as the prior and one as the conditional likelihood.
    
    Parameters:
    
    other - Other Gaussian to multiply with this.
    
    Returns:
    
    Multiplied Gaussians.
  - convolve
```
public MultivariateGaussian convolve(MultivariateGaussian other)
```
    Convolves this Gaussian with the other Gaussian.
    
    Parameters:
    
    other - Other Gaussian to convolve with this.
    
    Returns:
    
    Convolved Gaussians.
  - getInputDimensionality
```
public int getInputDimensionality()
```
    Gets the dimensionality of the Gaussian. This is the expected dimensionality of the vectors that can be used with the Gaussian.
    
    Returns:
    
    The dimensionality of the multivariate Gaussian.
  - getMean
```
public Vector getMean()
```
    Description copied from interface: DistributionWithMean
    
    Gets the arithmetic mean, or "first central moment" or "expectation", of the distribution.
    
    Specified by:
    
    getMean in interface DistributionWithMean<Vector>
    
    Returns:
    
    Mean of the distribution.
  - setMean
```
public void setMean(Vector mean)
```
    Sets the mean vector.
    
    Parameters:
    
    mean - The new mean, throws NullPointerException if null
  - getCovariance
```
public Matrix getCovariance()
```
    Gets the covariance matrix of the Gaussian.
    
    Returns:
    
    The covariance matrix of the Gaussian.
  - setCovariance
```
public void setCovariance(Matrix covariance)
```
    Sets the covariance matrix.
    
    Parameters:
    
    covariance - The new covariance matrix, the method forces the matrix to be symmetric by averaging the off-diagonal components into a clone of this parameter.
  - setCovariance
```
public void setCovariance(Matrix covariance,
                          double symmetryTolerance)
```
    Sets the covariance matrix.
    
    Parameters:
    
    covariance - The new covariance matrix, the method forces the matrix to be symmetric by averaging the off-diagonal components into a clone of this parameter.
    
    symmetryTolerance - Tolerance for symmetry check
  - getCovarianceInverse
```
public Matrix getCovarianceInverse()
```
    Gets the inverse of the covariance matrix.
    
    Returns:
    
    The inverse of the covariance matrix.
  - setCovarianceInverse
```
public void setCovarianceInverse(Matrix covarianceInverse)
```
    Sets the covariance inverse
    
    Parameters:
    
    covarianceInverse - Inverse of the covariance matrix
  - setCovarianceInverse
```
public void setCovarianceInverse(Matrix covarianceInverse,
                                 double symmetryTolerance)
```
    Sets the covariance inverse
    
    Parameters:
    
    covarianceInverse - Inverse of the covariance matrix
    
    symmetryTolerance - Tolerance to enforce symmetry
  - getLogCovarianceDeterminant
```
public double getLogCovarianceDeterminant()
```
    Getter for logCovarianceDeterminant
    
    Returns:
    
    Natural logarithm of the covariance matrix, automatically computed.
  - getLogLeadingCoefficient
```
public double getLogLeadingCoefficient()
```
    Getter for logLeadingCoefficient
    
    Returns:
    
    Natural logarithm of the leading likelihood coefficient, automatically computed.
  - equals
```
public boolean equals(java.lang.Object randomVariable)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - sampleInto
```
public void sampleInto(java.util.Random random,
                       int sampleCount,
                       java.util.Collection<? super Vector> output)
```
    Description copied from interface: Distribution
    
    Draws multiple random samples from the distribution and puts the result into the given collection.
    
    Specified by:
    
    sampleInto in interface Distribution<Vector>
    
    Parameters:
    
    random - Random number generator to use.
    
    sampleCount - The number of samples to draw. Cannot be negative.
    
    output - The collection to add the samples into.
  - sample
```
public static java.util.ArrayList<Vector> sample(Vector mean,
                                                 Matrix covarianceSquareRoot,
                                                 java.util.Random random,
                                                 int sampleCount)
```
    Returns a collection of draws this Gaussian with the given mean and covariance. If you need random draws from a Gaussian many times, I would recommend that you cache the square-root decomposition of the covariance and pass that to the method randomCovarianceSquareRoot().
    
    Parameters:
    
    mean - mean of the Gaussian
    
    covarianceSquareRoot - square-root decomposition of the covariance of the Gaussian
    
    sampleCount - number of times to draw from this random variable
    
    random - Random-number generator
    
    Returns:
    
    ArrayList of Vectors drawn from this Gaussian distribution
  - sampleInto
```
public static void sampleInto(Vector mean,
                              Matrix covarianceSquareRoot,
                              java.util.Random random,
                              int sampleCount,
                              java.util.Collection<? super Vector> output)
```
    Performs a collection of draws this Gaussian with the given mean and covariance. If you need random draws from a Gaussian many times, I would recommend that you cache the square-root decomposition of the covariance and pass that to the method randomCovarianceSquareRoot().
    
    Parameters:
    
    mean - mean of the Gaussian
    
    covarianceSquareRoot - square-root decomposition of the covariance of the Gaussian
    
    sampleCount - number of times to draw from this random variable
    
    random - Random-number generator
    
    output - The collection to put the samples into.
  - sample
```
public static Vector sample(Vector mean,
                            Matrix covarianceSquareRoot,
                            java.util.Random random)
```
    Returns a single draw from the Gaussian with the given mean and covariance.
    
    Parameters:
    
    mean - mean of the Gaussian
    
    covarianceSquareRoot - square-root decomposition of the covariance of the Gaussian
    
    random - Random-number generator
    
    Returns:
    
    Vector drawn from this Gaussian distribution
  - scale
```
public MultivariateGaussian scale(Matrix premultiplyMatrix)
```
    Scales the MultivariateGaussian by premultiplying by the given Matrix
    
    Parameters:
    
    premultiplyMatrix - Matrix against which to premultiply this
    
    Returns:
    
    Scaled MultivariateGaussian
  - plus
```
public MultivariateGaussian plus(MultivariateGaussian other)
```
    Adds two MultivariateGaussian random variables together and returns the resulting MultivariateGaussian
    
    Parameters:
    
    other - MultivariateGaussian to add to this MultivariateGaussian
    
    Returns:
    
    Effective addition of the two MultivariateGaussian random variables
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - convertToVector
```
public Vector convertToVector()
```
    Description copied from interface: Vectorizable
    
    Converts the object to a vector.
    
    Specified by:
    
    convertToVector in interface Vectorizable
    
    Returns:
    
    The Vector form of the object.
  - convertFromVector
```
public void convertFromVector(Vector parameters)
```
    Description copied from interface: Vectorizable
    
    Converts the object from a Vector of parameters.
    
    Specified by:
    
    convertFromVector in interface Vectorizable
    
    Parameters:
    
    parameters - The parameters to incorporate.
  - getEstimator
```
public MultivariateGaussian.MaximumLikelihoodEstimator getEstimator()
```
    Description copied from interface: EstimableDistribution
    
    Gets an estimator associated with this distribution.
    
    Specified by:
    
    getEstimator in interface EstimableDistribution<Vector,MultivariateGaussian>
    
    Returns:
    
    A distribution estimator associated for this distribution.

Class MultivariateGaussian

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class gov.sandia.cognition.statistics.AbstractDistribution

Methods inherited from class java.lang.Object

Methods inherited from interface gov.sandia.cognition.statistics.Distribution

Field Detail

DEFAULT_COVARIANCE_SYMMETRY_TOLERANCE

DEFAULT_DIMENSIONALITY

LOG_TWO_PI

Constructor Detail

MultivariateGaussian

MultivariateGaussian

MultivariateGaussian

MultivariateGaussian

Method Detail

clone

getProbabilityFunction

computeZSquared

times

convolve

getInputDimensionality

getMean

setMean

getCovariance

setCovariance

setCovariance

getCovarianceInverse

setCovarianceInverse

setCovarianceInverse

getLogCovarianceDeterminant

getLogLeadingCoefficient

equals

hashCode

sampleInto

sample

sampleInto

sample

scale

plus

toString

convertToVector

convertFromVector

getEstimator