Package org.apache.commons.math4.legacy.random

Class CorrelatedVectorFactory

java.lang.Object

org.apache.commons.math4.legacy.random.CorrelatedVectorFactory

public class CorrelatedVectorFactory
extends Object

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 of 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 common case is when the generated vector should be drawn from a Multivariate Normal Distribution, usually using Cholesky decomposition. Other distributions are possible as long as the underlying sampler provides normalized values (unit standard deviation).

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.

Constructor Summary

Constructors

Constructor	Description
CorrelatedVectorFactory(double[] mean, RealMatrix covariance, double small)	Correlated vector factory.
CorrelatedVectorFactory(RealMatrix covariance, double small)	Null mean correlated vector factory.

Method Summary

Modifier and Type	Method	Description
Supplier<double[]>	gaussian(org.apache.commons.rng.UniformRandomProvider rng)
Supplier<double[]>	uniform(org.apache.commons.rng.UniformRandomProvider rng)

Methods inherited from class java.lang.Object

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

Constructor Detail

CorrelatedVectorFactory

public CorrelatedVectorFactory(double[] mean,
                               RealMatrix covariance,
                               double small)

Correlated vector factory.

Parameters:

mean - Expected mean values of the components.

covariance - Covariance matrix.

small - Diagonal elements threshold under which columns are considered to be dependent on previous ones and are discarded.

Throws:

NonPositiveDefiniteMatrixException - if the covariance matrix is not strictly positive definite.

DimensionMismatchException - if the mean and covariance arrays dimensions do not match.

CorrelatedVectorFactory

public CorrelatedVectorFactory(RealMatrix covariance,
                               double small)

Null mean correlated vector factory.

Parameters:

covariance - Covariance matrix.

small - Diagonal elements threshold under which columns are considered to be dependent on previous ones and are discarded.

Throws:

NonPositiveDefiniteMatrixException - if the covariance matrix is not strictly positive definite.

Method Detail

uniform

public Supplier<double[]> uniform(org.apache.commons.rng.UniformRandomProvider rng)

Parameters:

rng - RNG.

Returns:

a generator of vectors with correlated components sampled from a uniform distribution.

gaussian

public Supplier<double[]> gaussian(org.apache.commons.rng.UniformRandomProvider rng)

Parameters:

rng - RNG.

Returns:

a generator of vectors with correlated components sampled from a normal distribution.