javaslam.prob
Class Gaussian

java.lang.Object
  |
  +--javaslam.prob.Gaussian

public class Gaussian

extends Object

A Gaussian probability density over a set of vector-valued variables.

In the moment parameterization, the density is expressed as

p(x) = (1 / Z) exp {-0.5 (x - m)^T S^-1(x - m)}

where Z is a normalizing constant, and the vector m (mu) and the (positive definite) matrix S (sigma) are the parameters. m is the expected value (mean) of x and S is its covariance matrix.

In the canonical parameterization, the density is expressed as

p(x) = exp (a + h^Tx - (1/2) x^T L x)

where a is a normalizing constant, and the vector h (eta) and the (positive definite) matrix L (lambda) are the parameters.

The parameters of the moment and canonical representations are related by

S = L^-1
m = L^-1h

Because some operations are more efficient or more numerically stable in one or the other parameterization, this class uses both representations. When an operation is unsupported by the current parameterization, the user must first reparameterize(boolean) the density, or else an IllegalStateException will be thrown.

This class records counts of all floating point operations using Flops.count(long) (except those used in the service of debugging and avoiding numerical errors).

Field Summary

protected boolean	doubling If true, then the capacity (i.e., the actual dimension of vP and mP) of this Gaussian is doubled when it must be increased to accomodate new variables; otherwise it is increased only enough to admit the new variables.
protected boolean	isMoment A field indicating whether this Gaussian is currently represented in the moment parameterization.
protected Matrix	mP The positive definite matrix parameter; this is S if isMoment is true and L otherwise.
protected Set	variables An unmodifiable ordered set whose elements are the Variables bound by this Gaussian.
protected ListSet	vars An ordered set whose elements are the Variables bound by this Gaussian.
protected HashMap	varsToStarts A map whose keys are the Variables bound by this Gaussian and whose values are Integers giving the starting index of the corresponding subvectors of vP and subblocks of mP.
protected Matrix	vP The vector parameter; this is m if isMoment is true and h otherwise.

Constructor Summary

Gaussian(boolean isMoment)
Default constructor.

Gaussian(boolean isMoment, int capacity)
Default constructor.

Gaussian(Gaussian p)
Copy constructor.

Gaussian(Gaussian p, Gaussian q)
Separator Gaussian constructor.

Gaussian(ListSet vars, double[] vP, double[][] mP, boolean isMoment)
Constructor.

Gaussian(ListSet vars, Matrix vP, Matrix mP, boolean isMoment)
Constructor.

Gaussian(Set vars, boolean isMoment)
Creates an uninformative Gaussian density over the supplied set of variables.

Method Summary

protected void	clear() Clears all variables from this Gaussian.
Gaussian	condition(ListSet cvars, Matrix obs, boolean inPlace) Conditions on a subset of the variables in this Gaussian.
Gaussian	div(Gaussian p, boolean inPlace) Divides two Gaussians (in the canonical parameterization).
double	entropy() Computes the differential entropy H of this Gaussian.
void	extend(Set vars) Extends this Gaussian to include a new set of variables.
int	getDimension() Gets the sum of the dimensions of all variables bound by this Gaussian.
Matrix	getEta(ListSet vars) Gets a subvector of h.
int[]	getIndices(ListSet vars) Gets an array of indices into the parameters that corresponds to the supplied set of variables.
Matrix	getLambda(ListSet rowVars, ListSet colVars) Gets a submatrix of L.
Matrix	getMu(ListSet vars) Gets a subvector of m.
Matrix	getSigma(ListSet rowVars, ListSet colVars) Gets a submatrix of S.
int	getSize() Returns the number of variables bound by this Gaussian.
Set	getVariables() Returns an unmodifiable ordered set of the Variables bound by this Gaussian.
protected void	initialize(ListSet vars, Matrix vP, Matrix mP) Initializes this Gaussian using the supplied arguments.
boolean	isCanonical() Returns true if this Gaussian is represented using the canonical parameterization, i.e., using the vector h and the (positive definite) matrix L.
boolean	isMoment() Returns true if this Gaussian is represented using the moment parameterization, i.e., using the mean vector m and the (positive definite) covariance matrix S.
double	kl(Gaussian q) Computes the relative entropy (Kullback-Liebler divergence) from this Gaussian to the supplied Gaussian.
double	likelihood(double[] val) Computes the likelihood of a particular value under this distribution.
Gaussian	marginalize(Set vars, boolean inPlace) Marginalizes out a subset of the variables in this Gaussian.
void	marginalizeOut(Set mvars) Marginalizes a set of variables out of this Gaussian (in place).
double	mutualInformation(Set x, Set y, Set z) Computes the (conditional) mutual information I(x;y - x|z) in nats (natural logarithmic units).
void	paint(Graphics2D g, double conf) Paints a 2D confidence ellipse for the first two dimensions of this Gaussian distribution.
void	rename(Variable var, Variable subst) Renames a variable in this Gaussian.
Gaussian	reparameterize(boolean inPlace) Reparameterizes this Gaussian; i.e., the parameterization will be switched from the canonical to the moment parameterization, or vice-versa.
Matrix	sample(int n, Random r) Samples from this Gaussian distribution.
void	set(Gaussian p) Sets this Gaussian equal to the supplied Gaussian.
void	setDoubling(boolean on) Controls the memory allocation behavior of this Gaussian.
void	setEta(ListSet vars, Matrix eta) Sets a subvector of h.
void	setLambda(ListSet rowVars, ListSet colVars, Matrix lambda) Sets a submatrix of L.
void	setMu(ListSet vars, Matrix mu) Sets a subvector of m.
void	setSigma(ListSet rowVars, ListSet colVars, Matrix sigma) Sets a submatrix of S.
Gaussian	times(Gaussian p, boolean inPlace) Multiplies two Gaussians.
String	toString() Creates a simple String representation of this Gaussian that prints out its parameters using Matlab notation.

Methods inherited from class java.lang.Object

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

Field Detail

varsToStarts

protected final HashMap varsToStarts

A map whose keys are the Variables bound by this Gaussian and whose values are Integers giving the starting index of the corresponding subvectors of vP and subblocks of mP.

vars

protected ListSet vars

An ordered set whose elements are the Variables bound by this Gaussian. The iteration order of the set is the storage order of the parameters.

variables

protected final Set variables

An unmodifiable ordered set whose elements are the Variables bound by this Gaussian. The iteration order of the set is the storage order of the parameters. This is merely a wrapper over vars.

isMoment

protected boolean isMoment

A field indicating whether this Gaussian is currently represented in the moment parameterization.

vP

protected Matrix vP

The vector parameter; this is m if isMoment is true and h otherwise. The length of this vector is greater than or equal to the sum of the dimensions of the variables bound by this Gaussian.

mP

protected Matrix mP

The positive definite matrix parameter; this is S if isMoment is true and L otherwise. This matrix is always square, and the lengths of its sides are greater than or equal to the sum of the dimensions of the variables bound by this Gaussian.

doubling

protected boolean doubling

If true, then the capacity (i.e., the actual dimension of vP and mP) of this Gaussian is doubled when it must be increased to accomodate new variables; otherwise it is increased only enough to admit the new variables.

Constructor Detail

Gaussian

public Gaussian(boolean isMoment)

Default constructor.

Parameters:

isMoment - true if this Gaussian should be represented in the moment parameterization

Gaussian

public Gaussian(boolean isMoment,
                int capacity)

Default constructor.

Parameters:

isMoment - true if this Gaussian should be represented in the moment parameterization

capacity - the initial capacity of the parameter matrices

Gaussian

public Gaussian(Gaussian p)

Copy constructor. This object becomes a deep copy of the supplied Gaussian density.

Gaussian

public Gaussian(Set vars,
                boolean isMoment)

Creates an uninformative Gaussian density over the supplied set of variables. Note that this is an ill-conditioned density: in the moment parameterization, this implies zero mean and infinite spherical covariance; in the canonical parameterization, this implies zero information vector and matrix. vP and mP are structured so that their blocks are ordered consistently with the iteration order of vars.

Parameters:

vars - a set of Variable objects

isMoment - true if this Gaussian should be represented in the moment parameterization

Gaussian

public Gaussian(Gaussian p,
                Gaussian q)

Separator Gaussian constructor. This Gaussian's variables are the intersection of those variables in the supplied Gaussians, and its density is uninformative. Note that this is an ill-conditioned density: in the moment parameterization, this implies zero mean and infinite spherical covariance; in the canonical parameterization, this implies zero information vector and matrix.

Parameters:

p - a Gaussian density

q - a Gaussian density

Gaussian

public Gaussian(ListSet vars,
                Matrix vP,
                Matrix mP,
                boolean isMoment)

Constructor. The parameters are not copied.

Parameters:

vars - an ordered set of Variable objects

vP - a column vector whose length matches the sum dimensions of the variables and whose subvectors are ordered consistently with the order of vars

mP - a positive definite matrix whose lengths match the sum dimensions of the variables and whose blocks are ordered consistently with the order of vars

isMoment - if true, then vP is interpreted as m and mP is interpreted as S; otherwise, vP is interpreted as h and mP is interpreted as L

Throws:

IllegalArgumentException - if mP is not square, or the dimensions of vP or mP do not match the sum dimension of vars

Gaussian

public Gaussian(ListSet vars,
                double[] vP,
                double[][] mP,
                boolean isMoment)

Constructor. The parameter objects are not copied.

Parameters:

vars - an ordered set of Variable objects

vP - a column vector whose length matches the sum dimensions of the variables and whose subvectors are ordered consistently with the order of vars

mP - a positive definite matrix whose lengths match the sum dimensions of the variables and whose blocks are ordered consistently with the order of vars

isMoment - if true, then vP is interpreted as m and mP is interpreted as S; otherwise, vP is interpreted as h and mP is interpreted as L

Throws:

IllegalArgumentException - if lambda is not square, or the dimensions of vP or mP do not match the sum dimension of vars

Method Detail

isMoment

public boolean isMoment()

Returns true if this Gaussian is represented using the moment parameterization, i.e., using the mean vector m and the (positive definite) covariance matrix S.

Returns:

true if this Gaussian is represented using the moment parameterization

isCanonical

public boolean isCanonical()

Returns true if this Gaussian is represented using the canonical parameterization, i.e., using the vector h and the (positive definite) matrix L.

Returns:

true if this Gaussian is represented using the canonical parameterization

reparameterize

public Gaussian reparameterize(boolean inPlace)

Reparameterizes this Gaussian; i.e., the parameterization will be switched from the canonical to the moment parameterization, or vice-versa.

Parameters:

inPlace - if true, then this Gaussian is internally reparameterized; otherwise a fresh Gaussian is constructed

Returns:

the reparameterized Gaussian

setDoubling

public void setDoubling(boolean on)

Controls the memory allocation behavior of this Gaussian. If on == true, then the capacity of the Gaussian (i.e., the lengths of vP and the sides of mP) is doubled whenever adding a variable to the Gaussian (via extend(java.util.Set)) would cause the capacity to be exceeded; otherwise, the capacity is increased only enough to admit the new variable. Doubling is off by default; Gaussians that are frequently extended should turn it on.

extend

public void extend(Set vars)

Extends this Gaussian to include a new set of variables. The parameters are initialized to be uninformed over the new variables. The subvectors of vP and blocks of mP are ordered consistently with the iteration order of vars.

Parameters:

vars - a set of Variable objects

initialize

protected void initialize(ListSet vars,
                          Matrix vP,
                          Matrix mP)

Initializes this Gaussian using the supplied arguments. The parameters are not copied.

Parameters:

vars - an ordered set of Variable objects.

vP - a column vector whose length matches the sum dimensions of the variables and whose subvectors are ordered consistently with the order of vars;

mP - a positive definite matrix whose lengths match the sum dimensions of the variables and whose blocks are ordered consistently with the order

Throws:

IllegalArgumentException - if mP is not square, or the dimensions of vP or mP do not match the sum dimension of vars

clear

protected void clear()

Clears all variables from this Gaussian.

rename

public void rename(Variable var,
                   Variable subst)

Renames a variable in this Gaussian.

Parameters:

var - the original variable

subst - the variable substituted for the original variable

Throws:

IllegalArgumentException - if var is not in this Gaussian or var and subst have differing dimension

getVariables

public Set getVariables()

Returns an unmodifiable ordered set of the Variables bound by this Gaussian. The iteration order of this set is the storage order of the parameters.

getDimension

public int getDimension()

Gets the sum of the dimensions of all variables bound by this Gaussian.

Returns:

the sum of the dimensions of all variables bound by this Gaussian

getSize

public int getSize()

Returns the number of variables bound by this Gaussian.

Returns:

the number of variables bound by this Gaussian

getIndices

public int[] getIndices(ListSet vars)

Gets an array of indices into the parameters that corresponds to the supplied set of variables. The order of the indices is determined by the order of vars.

Parameters:

vars - An ordered set of Variables; the indices corresponding to these variables is returned. If this Gaussian binds only one variable, then null is interpreted as the singleton containing the only variable bound by this Gaussian.

Returns:

an array of indices into the parameters that corresponds to vars

getEta

public Matrix getEta(ListSet vars)

Gets a subvector of h. The subvectors of h are ordered to be consistent with the iteration order of vars.

Parameters:

vars - an ordered set of Variables; if this is null, then it is like supplying the result of getVariables(), except the underlying parameter vector is returned, not copied

Returns:

A subvector of h; this is a copy unless vars == null

Throws:

IllegalStateException - if this Gaussian is not currently in the canonical parameterization

setEta

public void setEta(ListSet vars,
                   Matrix eta)

Sets a subvector of h. The subvectors of eta are assumed to be ordered consistently with the order of vars.

Parameters:

vars - an ordered set of Variables; this can be null if this Gaussian binds only one variable

eta - the new subvector value

Throws:

IllegalStateException - if this Gaussian is not currently in the canonical parameterization

getLambda

public Matrix getLambda(ListSet rowVars,
                        ListSet colVars)

Gets a submatrix of L. The blocks of L are ordered consistently with the orders of the index sets.

Parameters:

rowVars - an ordered set of Variables; if this is null, then it is like supplying the result of getVariables(), except the underlying parameter matrix is returned, not copied

colVars - an ordered set of Variables; use null to indicate that this is the same as rowVars

Returns:

A matrix consisting of blocks of L, as a Matrix object; this is a copy unless vars == null

Throws:

IllegalStateException - if this Gaussian is not currently in the canonical parameterization

setLambda

public void setLambda(ListSet rowVars,
                      ListSet colVars,
                      Matrix lambda)

Sets a submatrix of L. The blocks of lambda must be ordered consistently with the orders of the index sets. This method permits the setting of diagonal blocks or off diagonal blocks, but not both simultaneously; if off diagonal blocks are specified, then their transpose blocks are also set to maintain the symmetry of L.

Parameters:

rowVars - an ordered set of Variables; this can be null if this Gaussian binds only one variable

colVars - an ordered set of Variables; use null to indicate that this is the same as rowVars

lambda - the new submatrix value; this must be symmetric if colVars is null

Returns:

A matrix consisting of blocks of L, as a two-dimensional double array

Throws:

IllegalStateException - if this Gaussian is not currently in the canonical parameterization

IllegalArgumentException - if colVars is null and lambda is not symmetric

getMu

public Matrix getMu(ListSet vars)

Gets a subvector of m. The subvectors of m are ordered to be consistent with the iteration order of vars.

Parameters:

vars - an ordered set of Variables; if this is null, then it is like supplying the result of getVariables(), except the underlying parameter vector is returned, not copied

Returns:

A subvector of m; this is a copy unless vars == null

Throws:

IllegalStateException - if this Gaussian is not currently in the moment parameterization

setMu

public void setMu(ListSet vars,
                  Matrix mu)

Sets a subvector of m. The subvectors of mu are assumed to be ordered consistently with the order of vars.

Parameters:

vars - an ordered set of Variables; this can be null if this Gaussian binds only one variable

mu - the new subvector value

Throws:

IllegalStateException - if this Gaussian is not currently in the moment parameterization

getSigma

public Matrix getSigma(ListSet rowVars,
                       ListSet colVars)

Gets a submatrix of S. The blocks of S are ordered consistently with the orders of the index sets.

Parameters:

rowVars - an ordered set of Variables; if this is null, then it is like supplying the result of getVariables(), except the underlying parameter matrix is returned, not copied

colVars - an ordered set of Variables; use null to indicate that this is the same as rowVars

Returns:

A matrix consisting of blocks of S, as a Matrix object; this is a copy unless vars == null

Throws:

IllegalStateException - if this Gaussian is not currently in the moment parameterization

setSigma

public void setSigma(ListSet rowVars,
                     ListSet colVars,
                     Matrix sigma)

Sets a submatrix of S. The blocks of sigma must be ordered consistently with the orders of the index sets. This method permits the setting of diagonal blocks or off diagonal blocks, but not both simultaneously; if off diagonal blocks are specified, then their transpose blocks are also set to maintain the symmetry of S.

Parameters:

rowVars - an ordered set of Variables; this can be null if this Gaussian binds only one variable

colVars - an ordered set of Variables; use null to indicate that this is the same as rowVars

sigma - the new submatrix value; this must be symmetric if colVars is null

Returns:

A matrix consisting of blocks of S, as a two-dimensional double array

Throws:

IllegalStateException - if this Gaussian is not currently in the moment parameterization

IllegalArgumentException - if colVars is null and sigma is not symmetric

marginalizeOut

public void marginalizeOut(Set mvars)

Marginalizes a set of variables out of this Gaussian (in place).

Parameters:

mvars - a set of Variables to marginalize out; any of these that are not bound by the Gaussian are ignored

marginalize

public Gaussian marginalize(Set vars,
                            boolean inPlace)

Marginalizes out a subset of the variables in this Gaussian. The result uses the same parameterization as this Gaussian.

Parameters:

inPlace - if true, then the Gaussian is marginalized in place.

Returns:

this Gaussian with the variables in mvars marginalized out

Throws:

IllegalArgumentException - if this Gaussian does not contain the variables in rvars

condition

public Gaussian condition(ListSet cvars,
                          Matrix obs,
                          boolean inPlace)

Conditions on a subset of the variables in this Gaussian.

Parameters:

cvars - an ordered set of the Variables of this Gaussian being conditioned on

obs - a vector (whose length and order is consistent with cvars) representing the observation

inPlace - if true, the conditioning is done in-place.

Returns:

this Gaussian with the variables in cvars conditioned on

Throws:

IllegalArgumentException - if this Gaussian does not contain the variables in rvars

set

public void set(Gaussian p)

Sets this Gaussian equal to the supplied Gaussian.

times

public Gaussian times(Gaussian p,
                      boolean inPlace)

Multiplies two Gaussians. This method cannot be applied to Gaussians that are in different parameterizations, or to a pair of moment Gaussians that share variables.

Parameters:

inPlace - if true, then p is multiplied into this and this is returned.

Returns:

the product of this and p

Throws:

IllegalStateException - if this Gaussian or the supplied Gaussian are in the moment parameterization

div

public Gaussian div(Gaussian p,
                    boolean inPlace)

Divides two Gaussians (in the canonical parameterization).

Parameters:

inPlace - if true, then p is divided into this and this is returned.

Returns:

this divided by p

Throws:

IllegalArgumentException - if p binds variables not bound by this Gaussian

IllegalStateException - if this Gaussian or the supplied Gaussian are in the moment parameterization

entropy

public double entropy()

Computes the differential entropy H of this Gaussian.

Returns:

the differential entropy of this Gaussian (in nats, i.e., natural logarithmic units).

kl

public double kl(Gaussian q)

Computes the relative entropy (Kullback-Liebler divergence) from this Gaussian to the supplied Gaussian. This method is most efficient when this Gaussian is represented in moment form.

Returns:

D(this || q) (in nats, i.e., natural logarithmic units).

Throws:

IllegalArgumentException - if this and the supplied Gaussian do not cover the same set of variables

mutualInformation

public double mutualInformation(Set x,
                                Set y,
                                Set z)

Computes the (conditional) mutual information I(x;y - x|z) in nats (natural logarithmic units).

Parameters:

x - a set of Variables in this Gaussian

y - a set of Variables in this Gaussian

z - a set of Variables in this Gaussian

Returns:

I(x;y - x|z) in nats

Throws:

IllegalArgumentException - if x, y, or z contain variables not bound by this Gaussian

sample

public Matrix sample(int n,
                     Random r)

Samples from this Gaussian distribution. The distribution must be in the moment parameterization.

Parameters:

n - the number of samples to draw

r - the source of random bits

Returns:

a matrix with n columns, each of which is a sample from this distribution

likelihood

public double likelihood(double[] val)

Computes the likelihood of a particular value under this distribution.

Parameters:

val - the value

Returns:

the likelihood of val

Throws:

IllegalArgumentException - if the length of val does not equal the dimension of this distribution

toString

public String toString()

Creates a simple String representation of this Gaussian that prints out its parameters using Matlab notation.

Overrides:

toString in class Object

paint

public void paint(Graphics2D g,
                  double conf)

Paints a 2D confidence ellipse for the first two dimensions of this Gaussian distribution.