Name

---

    GENERATE_CORRELATED_DATA

Purpose

---

    This function will return a list of k normally-distributed,
    correlated, n-dimensional random points [with a specified
    mean vector and set of univariate standard deviations].

Category

---

    Statistics.

Calling Sequence

---

    Result = $
      GENERATE_CORRELATED_DATA, seed,
                                numberPoints,
                                correlationMatrix,
                                MEAN_VECTOR=meanVector,
                                STANDARD_DEVIATION=standardDeviation,

Inputs

---

    seed
      A variable or constant (long integer) used to initialize
      the random sequence on input, and in which the state of the
      random number generator is saved on output.
    numberPoints
      A variable or constant containing the number of n-dimensional
      values to be produced.
    correlationMatrix
      A two-dimensional matrix describing the correlation to be
      exhibited between variables. This matrix will also define
      the dimensionality of the produced data set (for example, a
      3x3 correlation matrix will cause 3-dimensional data to be
      generated).

Keyword Parameters

---

    MEAN_VECTOR
      A vector defining the mean for each dimension of the generated
      data set. If omitted, the mean vector will be filled with 0's.
    STANDARD_DEVIATION
      A vector defining the standard deviation for each dimension of
      the generated data set. If omitted, the standard deviation vector
      will be filled with 1's.

Return Value

---

    A matrix containing multi-dimensional, normally-distributed,
    correlated random values. The random values will be contained
    in the rows of the returned matrix.
   
    If the dimensions of the provided descriptive statistics are
    incompatible, a scaler value of -1 will be returned.
   
    If the dimensions of the data set, as determined from the
    provided correlation matrix is less than 2, then a scalar
    value of -2 will be returned.
   

Side Effects

---

    If the seed is specifed as any data type besides a long integer, it
    will be truncated and changed to this data type.

Modification History

---

    Written by: Carl Salvaggio
    April, 2009 Original code
   

Disclaimer

---

    This source code is provided "as is" and without warranties as to performance
    or merchantability. The author and/or distributors of this source code may
    have made statements about this source code. Any such statements do not
    constitute warranties and shall not be relied on by the user in deciding
    whether to use this source code.
    This source code is provided without any express or implied warranties
    whatsoever. Because of the diversity of conditions and hardware under which
    this source code may be used, no warranty of fitness for a particular purpose
    is offered. The user is advised to test the source code thoroughly before
    relying on it. The user must assume the entire risk of using the source code.