## 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 + hTx - (1/2) xT 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 `Variable`s bound by this Gaussian. `protected  ListSet` `vars`           An ordered set whose elements are the `Variable`s bound by this Gaussian. `protected  HashMap` `varsToStarts`           A map whose keys are the `Variable`s bound by this Gaussian and whose values are `Integer`s 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 `Variable`s 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 `Variable`s bound by this Gaussian and whose values are `Integer`s 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 `Variable`s 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 `Variable`s 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 `Variable`s 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; this can be `null` if this Gaussian binds only one variable
`colVars` - an ordered set of `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; 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 `Variable`s; this can be `null` if this Gaussian binds only one variable
`colVars` - an ordered set of `Variable`s; 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 `Variable`s 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 `Variable`s 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 `Variable`s in this Gaussian
`y` - a set of `Variable`s in this Gaussian
`z` - a set of `Variable`s 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.