svn commit: r1067588 - /commons/proper/math/trunk/src/site/xdoc/userguide/random.xml

[ps...@apache.org]

Author: psteitz
Date: Sun Feb  6 05:34:22 2011
New Revision: 1067588

URL: http://svn.apache.org/viewvc?rev=1067588&view=rev
Log:
Added correlated vector generation example.

Modified:
    commons/proper/math/trunk/src/site/xdoc/userguide/random.xml

Modified: commons/proper/math/trunk/src/site/xdoc/userguide/random.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/userguide/random.xml?rev=1067588&r1=1067587&r2=1067588&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/userguide/random.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/userguide/random.xml Sun Feb  6 05:34:22 2011
@@ -34,6 +34,7 @@
     The Commons Math random package includes utilities for
     <ul>
         <li>generating random numbers</li>
+        <li>generating random vectors</li>
         <li>generating random strings</li>
         <li>generating cryptographically secure sequences of random numbers or
          strings</li>
@@ -184,7 +185,48 @@ for (int i = 0; i &lt; 1000; i++) {
     href="http://en.wikipedia.org/wiki/Multivariate_normal_distribution">
     Multivariate Normal Distribution</a>.
     </p>
- </subsection>
+    <p><dl>
+    <dt>Generating random vectors from a bivariate normal distribution</dt><dd>
+    <source>
+// Create and seed a RandomGenerator (could use any of the generators in the random package here)
+RandomGenerator rg = new JDKRandomGenerator();
+rg.setSeed(17399225432l);  // Fixed seed means same results every time
+
+// Create a GassianRandomGenerator using rg as its source of randomness
+GaussianRandomGenerator rawGenerator = new GaussianRandomGenerator(rg);
+
+// Create a CorrelatedRandomVectorGenerator using rawGenerator for the components
+CorrelatedRandomVectorGenerator generator = 
+    new CorrelatedRandomVectorGenerator(mean, covariance, 1.0e-12 * covariance.getNorm(), rawGenerator);
+
+// Use the generator to generate correlated vectors
+double[] randomVector = generator.nextVector();
+... </source>
+    The <code>mean</code> argument is a double[] array holding the means of the random vector
+    components.  In the bivariate case, it must have length 2.  The <code>covariance</code> argument
+    is a RealMatrix, which needs to be 2 x 2.  The main diagonal elements are the
+    variances of the vector components and the off-diagonal elements are the covariances.
+    For example, if the means are 1 and 2 respectively, and the desired standard deviations
+    are 3 and 4, respectively, then we need to use
+    <source>
+double[] mean = {1, 2};
+double[][] cov = {{9, c}, {c, 16}};
+RealMatrix covariance = MatrixUtils.createRealMatrix(cov); </source>
+    where c is the desired covariance. If you are starting with a desired correlation,
+    you need to translate this to a covariance by multiplying it by the product of the
+    standard deviations.  For example, if you want to generate data that will give Pearson's
+    R of 0.5, you would use c = 3 * 4 * .5 = 6.
+    </dd></dl></p>
+    <p>
+    In addition to multivariate normal distributions, correlated vectors from multivariate uniform
+    distributions can be generated by creating a
+    <a href="../apidocs/org/apache/commons/math/random/UniformRandomGenerator.html">UniformRandomGenerator</a>
+    in place of the 
+    <code>GaussianRandomGenerator</code> above.  More generally, any
+    <a href="../apidocs/org/apache/commons/math/random/NormalizedRandomGenerator.html">NormalizedRandomGenerator</a>
+    may be used.
+    </p>
+</subsection>
 
 <subsection name="2.4 Random Strings" href="strings">
     <p>