org.apache.commons.math3.random

## Class CorrelatedRandomVectorGenerator

- java.lang.Object
- - org.apache.commons.math3.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:
    $Id: CorrelatedRandomVectorGenerator.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private NormalizedRandomGenerator` | `generator` Underlying generator.
    `private double[]` | `mean` Mean vector.
    `private double[]` | `normalized` Storage for the normalized vector.
    `private RealMatrix` | `root` Root of the covariance matrix.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CorrelatedRandomVectorGenerator(double[] mean, RealMatrix covariance, double small, NormalizedRandomGenerator generator)` Builds a correlated random vector generator from its mean vector and covariance matrix.
    `CorrelatedRandomVectorGenerator(RealMatrix covariance, double small, NormalizedRandomGenerator generator)` Builds a null mean random correlated vector generator from its covariance matrix.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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 final RealMatrix root

      Root of the covariance matrix.

  - ### Constructor Detail

    - #### CorrelatedRandomVectorGenerator

          public CorrelatedRandomVectorGenerator(double[] mean,
                                         RealMatrix covariance,
                                         double small,
                                         NormalizedRandomGenerator generator)

      Builds 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:
        `NonPositiveDefiniteMatrixException` - if the covariance matrix is not strictly positive definite.
        `DimensionMismatchException` - if the mean and covariance arrays dimensions do not match.

    - #### CorrelatedRandomVectorGenerator

          public CorrelatedRandomVectorGenerator(RealMatrix covariance,
                                         double small,
                                         NormalizedRandomGenerator generator)

      Builds 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:
        `NonPositiveDefiniteMatrixException` - 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

    - #### 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 root matrix.
      Returns:
        rank of the square matrix.
      See Also:
        `getRootMatrix()`

    - #### 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()`

    - #### 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-2013 Apache Software Foundation