org.apache.commons.math.random
Class CorrelatedRandomVectorGenerator

java.lang.Object
  extended by org.apache.commons.math.random.CorrelatedRandomVectorGenerator
All Implemented Interfaces:
RandomVectorGenerator

public class CorrelatedRandomVectorGenerator
extends java.lang.Object
implements RandomVectorGenerator

A RandomVectorGenerator that generates vectors with with correlated components.

Random vectors with correlated components are built by combining the uncorrelated components of another random vector in such a way that the resulting correlations are the ones specified by a positive definite covariance matrix.

The main use for correlated random vector generation is for Monte-Carlo simulation of physical problems with several variables, for example to generate error vectors to be added to a nominal vector. A particularly interesting case is when the generated vector should be drawn from a Multivariate Normal Distribution. The approach using a Cholesky decomposition is quite usual in this case. However, it can be extended to other cases as long as the underlying random generator provides normalized values like GaussianRandomGenerator or UniformRandomGenerator.

Sometimes, the covariance matrix for a given simulation is not strictly positive definite. This means that the correlations are not all independent from each other. In this case, however, the non strictly positive elements found during the Cholesky decomposition of the covariance matrix should not be negative either, they should be null. Another non-conventional extension handling this case is used here. Rather than computing C = UT.U where C is the covariance matrix and U is an upper-triangular matrix, we compute C = B.BT where B is a rectangular matrix having more rows than columns. The number of columns of B is the rank of the covariance matrix, and it is the dimension of the uncorrelated random vector that is needed to compute the component of the correlated vector. This class handles this situation automatically.

Since:
1.2
Version:
$Revision: 1043908 $ $Date: 2010-12-09 12:53:14 +0100 (jeu. 09 d??c. 2010) $

Field Summary
private  NormalizedRandomGenerator generator
          Underlying generator.
private  double[] mean
          Mean vector.
private  double[] normalized
          Storage for the normalized vector.
private  int rank
          Rank of the covariance matrix.
private  RealMatrix root
          Permutated Cholesky root of the covariance matrix.
 
Constructor Summary
CorrelatedRandomVectorGenerator(double[] mean, RealMatrix covariance, double small, NormalizedRandomGenerator generator)
          Simple constructor.
CorrelatedRandomVectorGenerator(RealMatrix covariance, double small, NormalizedRandomGenerator generator)
          Simple constructor.
 
Method Summary
private  void decompose(RealMatrix covariance, double small)
          Decompose the original square matrix.
 NormalizedRandomGenerator getGenerator()
          Get the underlying normalized components generator.
 int getRank()
          Get the rank of the covariance matrix.
 RealMatrix getRootMatrix()
          Get the root of the covariance matrix.
 double[] nextVector()
          Generate a correlated random vector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mean

private final double[] mean
Mean vector.


generator

private final NormalizedRandomGenerator generator
Underlying generator.


normalized

private final double[] normalized
Storage for the normalized vector.


root

private RealMatrix root
Permutated Cholesky root of the covariance matrix.


rank

private int rank
Rank of the covariance matrix.

Constructor Detail

CorrelatedRandomVectorGenerator

public CorrelatedRandomVectorGenerator(double[] mean,
                                       RealMatrix covariance,
                                       double small,
                                       NormalizedRandomGenerator generator)
                                throws NotPositiveDefiniteMatrixException,
                                       DimensionMismatchException
Simple constructor.

Build a correlated random vector generator from its mean vector and covariance matrix.

Parameters:
mean - expected mean values for all components
covariance - covariance matrix
small - diagonal elements threshold under which column are considered to be dependent on previous ones and are discarded
generator - underlying generator for uncorrelated normalized components
Throws:
java.lang.IllegalArgumentException - if there is a dimension mismatch between the mean vector and the covariance matrix
NotPositiveDefiniteMatrixException - if the covariance matrix is not strictly positive definite
DimensionMismatchException - if the mean and covariance arrays dimensions don't match

CorrelatedRandomVectorGenerator

public CorrelatedRandomVectorGenerator(RealMatrix covariance,
                                       double small,
                                       NormalizedRandomGenerator generator)
                                throws NotPositiveDefiniteMatrixException
Simple constructor.

Build a null mean random correlated vector generator from its covariance matrix.

Parameters:
covariance - covariance matrix
small - diagonal elements threshold under which column are considered to be dependent on previous ones and are discarded
generator - underlying generator for uncorrelated normalized components
Throws:
NotPositiveDefiniteMatrixException - if the covariance matrix is not strictly positive definite
Method Detail

getGenerator

public NormalizedRandomGenerator getGenerator()
Get the underlying normalized components generator.

Returns:
underlying uncorrelated components generator

getRootMatrix

public RealMatrix getRootMatrix()
Get the root of the covariance matrix. The root is the rectangular matrix B such that the covariance matrix is equal to B.BT

Returns:
root of the square matrix
See Also:
getRank()

getRank

public int getRank()
Get the rank of the covariance matrix. The rank is the number of independent rows in the covariance matrix, it is also the number of columns of the rectangular matrix of the decomposition.

Returns:
rank of the square matrix.
See Also:
getRootMatrix()

decompose

private void decompose(RealMatrix covariance,
                       double small)
                throws NotPositiveDefiniteMatrixException
Decompose the original square matrix.

The decomposition is based on a Choleski decomposition where additional transforms are performed:

This means that rather than computing M = UT.U where U is an upper triangular matrix, this method computed M=B.BT where B is a rectangular matrix.

Parameters:
covariance - covariance matrix
small - diagonal elements threshold under which column are considered to be dependent on previous ones and are discarded
Throws:
NotPositiveDefiniteMatrixException - if the covariance matrix is not strictly positive definite

nextVector

public double[] nextVector()
Generate a correlated random vector.

Specified by:
nextVector in interface RandomVectorGenerator
Returns:
a random vector as an array of double. The returned array is created at each call, the caller can do what it wants with it.


Copyright (c) 2003-2011 Apache Software Foundation