Author: psteitz
Date: Sun Feb 6 05:42:35 2011
New Revision: 1067592
URL: http://svn.apache.org/viewvc?rev=1067592&view=rev
Log:
Added correlated vector generation example.
Modified:
commons/proper/math/branches/MATH_2_X/src/site/xdoc/userguide/random.xml
Modified:
commons/proper/math/branches/MATH_2_X/src/site/xdoc/userguide/random.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/branches/MATH_2_X/src/site/xdoc/userguide/random.xml?rev=1067592&r1=1067591&r2=1067592&view=diff
==============================================================================
--- commons/proper/math/branches/MATH_2_X/src/site/xdoc/userguide/random.xml
(original)
+++ commons/proper/math/branches/MATH_2_X/src/site/xdoc/userguide/random.xml
Sun Feb 6 05:42:35 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 < 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>
