gov.sandia.cognition.statistics.distribution
Class MultivariateGaussian

java.lang.Object
  extended by gov.sandia.cognition.util.AbstractCloneableSerializable
      extended by gov.sandia.cognition.statistics.AbstractDistribution<Vector>
          extended by gov.sandia.cognition.statistics.distribution.MultivariateGaussian
All Implemented Interfaces:
Vectorizable, ClosedFormComputableDistribution<Vector>, ClosedFormDistribution<Vector>, ComputableDistribution<Vector>, Distribution<Vector>, DistributionWithMean<Vector>, EstimableDistribution<Vector,MultivariateGaussian>, CloneableSerializable, Serializable, 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
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
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
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
 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(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
 ArrayList<Vector> sample(Random random, int numSamples)
          Draws multiple random samples from the distribution.
static Vector sample(Vector mean, Matrix covarianceSquareRoot, Random random)
          Returns a single draw from the Gaussian with the given mean and covariance.
static ArrayList<Vector> sample(Vector mean, Matrix covarianceSquareRoot, Random random, int numDraws)
          Returns 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.
 String toString()
           
 
Methods inherited from class gov.sandia.cognition.statistics.AbstractDistribution
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
 

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(Object randomVariable)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

sample

public ArrayList<Vector> sample(Random random,
                                int numSamples)
Description copied from interface: Distribution
Draws multiple random samples from the distribution. It is generally more efficient to use this multiple-sample method than multiple calls of the single-sample method. (But not always.)

Specified by:
sample in interface Distribution<Vector>
Parameters:
random - Random-number generator to use in order to generate random numbers.
numSamples - Number of samples to draw from the distribution.
Returns:
Samples drawn according to this distribution.

sample

public static ArrayList<Vector> sample(Vector mean,
                                       Matrix covarianceSquareRoot,
                                       Random random,
                                       int numDraws)
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
numDraws - number of times to draw from this random variable
random - Random-number generator
Returns:
ArrayList of Vectors drawn from this Gaussian distribution

sample

public static Vector sample(Vector mean,
                            Matrix covarianceSquareRoot,
                            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 String toString()
Overrides:
toString in class 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.