comirva.audio.util.gmm
Class GaussianMixture

java.lang.Object
  comirva.audio.util.gmm.GaussianMixture

All Implemented Interfaces:

XMLSerializable

public final class GaussianMixture
extends java.lang.Object
implements XMLSerializable

Gaussian Mixture Model

Description

This class implements in combination with GaussianComponent a gaussian mixture model. To create a gaussian mixture model you have to specify means, covariances and the weight for each of the gaussian components. GaussianMixture and GaussianComponent do not only model a GMM, but also support training GMMs using the EM algorithm.

Take a look at KMeansClustering for initializing the GMM.

One notable aspect regarding the implementation is the fact that if the covariance matrix of any of the components of this GMM gets singular during the training process a CovarianceSingularityException is thrown. The CovarianceSingularityException contains a reduced PointList. All points belonging to the singular component have been removed. So after the reduction one can try to rerun the training Algorithm with the reduced PointList.

Another aspect of the design of this class was influenced by the limited memory on real world computers. To improve performance a buffer to store some estimations is used. This buffer is static to reduce garbage collection time and all training processes are synchronized on this buffer. Consequently one can only train one GMM instance at a time.

New in version 1.1:
- The cholesky decomposition is used to speed up computations.

See Also:

KMeansClustering, GaussianComponent

Constructor Summary

GaussianMixture(double[] componentWeights, Matrix[] means, Matrix[] covariances)
This constructor creates a GMM and checks the parameters for plausibility.

GaussianMixture(GaussianComponent[] components)
This constructor creates a GMM and checks the components for compatibility.

Method Summary

int	getDimension() Returns the number of dimensions of the GMM.
double	getLogLikelihood(PointList points) Returns the log likelihood of the points stored in the pointlist under the assumption the these points where sample from this GMM.
Matrix	getMean(int numberOfComponent) For testing purpose only.
double	getProbability(Matrix x) Returns the probability of a single sample point under the assumption that it was draw from the distribution represented by this GMM.
double[]	nextSample() Draws a sample from this GMM.
void	print() Prints some information about this gaussian component.
static GaussianMixture	readGMM(javax.xml.stream.XMLStreamReader parser) This method allows to read a GMM from a xml input stream as recommended by the XMLSerializable interface.
void	readXML(javax.xml.stream.XMLStreamReader parser) Reads the xml representation of an object form the xml input stream.
void	runEM(PointList samplePoints) Runs the EM algorithm to train this GMM given the sample points in the PointList.
void	writeXML(javax.xml.stream.XMLStreamWriter writer) Writes the xml representation of this object to the xml output stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

GaussianMixture

public GaussianMixture(double[] componentWeights,
                       Matrix[] means,
                       Matrix[] covariances)
                throws java.lang.IllegalArgumentException

This constructor creates a GMM and checks the parameters for plausibility. The weights, means and covariances of every component are passed as arrays to the constructor. The i-th component therefore is completely defined by the i-th entries within these arrays.

Parameters:

componentWeights - double[] specifies the components weights

means - Matrix[] specifies the components mean vectors

covariances - Matrix[] specifies the components covariance matrices

Throws:

java.lang.IllegalArgumentException - if any invalid parameter settings are detected while checking them

GaussianMixture

public GaussianMixture(GaussianComponent[] components)
                throws java.lang.IllegalArgumentException

This constructor creates a GMM and checks the components for compatibility. The components themselves have been checked during their construction.

Parameters:

components - GaussianComponent[] an array of gaussian components

Throws:

java.lang.IllegalArgumentException - if the passed components are not compatible

Method Detail

getLogLikelihood

public double getLogLikelihood(PointList points)

Returns the log likelihood of the points stored in the pointlist under the assumption the these points where sample from this GMM.

[SUM over all j: log (SUM over all i:(p(x_j | C = i) * P(C = i)))]

Parameters:

points - PointList list of sample points to estimate the log likelihood of

Returns:

double the log likelihood of drawing these samples from this gmm

nextSample

public double[] nextSample()

Draws a sample from this GMM.

Returns:

double[] a sample drawn from this distribution

getProbability

public double getProbability(Matrix x)

Returns the probability of a single sample point under the assumption that it was draw from the distribution represented by this GMM.

[SUM over all i:(p(x | C = i) * P(C = i))]

Parameters:

x - Matrix a sample point

Returns:

double the probability of the given sample

getDimension

public int getDimension()

Returns the number of dimensions of the GMM.

Returns:

int number of dimensions

print

public void print()

Prints some information about this gaussian component. This is for debugging purpose only.

getMean

public Matrix getMean(int numberOfComponent)

For testing purpose only.

Parameters:

numberOfComponent - int the number of the component

Returns:

Matrix the mean vector

readGMM

public static GaussianMixture readGMM(javax.xml.stream.XMLStreamReader parser)
                               throws java.io.IOException,
                                      javax.xml.stream.XMLStreamException

This method allows to read a GMM from a xml input stream as recommended by the XMLSerializable interface.

Parameters:

parser - XMLStreamReader the xml input stream

Returns:

GaussianMixture the GMM read from the xml stream

Throws:

java.io.IOException - raised, if there are any io troubles

javax.xml.stream.XMLStreamException - raised, if there are any parsing errors

See Also:

XMLSerializable

runEM

public void runEM(PointList samplePoints)
           throws CovarianceSingularityException

Runs the EM algorithm to train this GMM given the sample points in the PointList. The EM algorithm runs till either one cannot yield an improvement of the log likelihood or the number of training iterations exceeds the number of maximal allowed iterations(MAX_ITERATIONS).

Parameters:

samplePoints - PointList sample points of the distribution to approximate by this GMM

Throws:

CovarianceSingularityException - thrown if any of the gaussian components got singular

writeXML

public void writeXML(javax.xml.stream.XMLStreamWriter writer)
              throws java.io.IOException,
                     javax.xml.stream.XMLStreamException

Writes the xml representation of this object to the xml output stream.

There is the convention, that each call to a writeXML() method results in one xml element in the output stream.

Specified by:

writeXML in interface XMLSerializable

Parameters:

writer - XMLStreamWriter the xml output stream

Throws:

java.io.IOException - raised, if there are any io troubles

javax.xml.stream.XMLStreamException - raised, if there are any parsing errors

readXML

public void readXML(javax.xml.stream.XMLStreamReader parser)
             throws java.io.IOException,
                    javax.xml.stream.XMLStreamException

Reads the xml representation of an object form the xml input stream.

There is the convention, that readXML() starts parsing by checking the start tag of this object and finishes parsing by checking the end tag. The caller has to ensure, that at method entry the current token is the start tag. After the method call it's the callers responsibility to move from the end tag to the next token.

Specified by:

readXML in interface XMLSerializable

Parameters:

parser - XMLStreamReader the xml input stream

Throws:

java.io.IOException - raised, if there are any io troubles

javax.xml.stream.XMLStreamException - raised, if there are any parsing errors