[Numpy-svn] r5359 - trunk/numpy/doc

[numpy-svn at scipy.org]

Author: stefan
Date: 2008-07-08 02:49:25 -0500 (Tue, 08 Jul 2008)
New Revision: 5359

Added:
   trunk/numpy/doc/EXAMPLE_DOCSTRING.txt
Log:
Example of real docstring.


Added: trunk/numpy/doc/EXAMPLE_DOCSTRING.txt
===================================================================
--- trunk/numpy/doc/EXAMPLE_DOCSTRING.txt	2008-07-08 07:29:23 UTC (rev 5358)
+++ trunk/numpy/doc/EXAMPLE_DOCSTRING.txt	2008-07-08 07:49:25 UTC (rev 5359)
@@ -0,0 +1,103 @@
+.. Here follows an example docstring for a C-function.  Note that the
+   signature is given.  This is done only for functions written is C,
+   since Python cannot find their signature by inspection.  For all
+   other functions, start with the one line description.
+
+
+multivariate_normal(mean, cov[, shape])
+
+Draw samples from a multivariate normal distribution.
+
+The multivariate normal, multinormal or Gaussian distribution is a
+generalisation of the one-dimensional normal distribution to higher
+dimensions.
+
+Such a distribution is specified by its mean and covariance matrix,
+which are analogous to the mean (average or "centre") and variance
+(standard deviation squared or "width") of the one-dimensional normal
+distribution.
+
+Parameters
+----------
+mean : (N,) ndarray
+    Mean of the N-dimensional distribution.
+cov : (N,N) ndarray
+    Covariance matrix of the distribution.
+shape : tuple of ints, optional
+    Given a shape of, for example, (m,n,k), m*n*k samples are
+    generated, and packed in an m-by-n-by-k arrangement.  Because each
+    sample is N-dimensional, the output shape is (m,n,k,N).  If no
+    shape is specified, a single sample is returned.
+
+Returns
+-------
+out : ndarray
+    The drawn samples, arranged according to `shape`.  If the
+    shape given is (m,n,...), then the shape of `out` is is
+    (m,n,...,N).
+
+    In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
+    value drawn from the distribution.
+
+See Also
+--------
+normal
+scipy.stats.distributions.norm : Provides random variates, as well as
+                                 probability density function, cumulative
+                                 density function, etc.
+
+Notes
+-----
+The mean is a coordinate in N-dimensional space, which represents the
+location where samples are most likely to be generated.  This is
+analogous to the peak of the bell curve for the one-dimensional or
+univariate normal distribution.
+
+Covariance indicates the level to which two variables vary together.
+From the multivariate normal distribution, we draw N-dimensional
+samples, :math:`X = [x_1, x_2, ... x_N]`.  The covariance matrix
+element :math:`C_ij` is the covariance of :math:`x_i` and :math:`x_j`.
+The element :math:`C_ii` is the variance of :math:`x_i` (i.e. its
+"spread").
+
+Instead of specifying the full covariance matrix, popular
+approximations include:
+
+  - Spherical covariance (`cov` is a multiple of the identity matrix)
+  - Diagonal covariance (`cov` has non-negative elements, and only on
+    the diagonal)
+
+This geometrical property can be seen in two dimensions by plotting
+generated data-points:
+
+>>> mean = [0,0]
+>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
+
+>>> x,y = numpy.multivariate_normal(mean,cov,5000).T
+>>> pyplot.plot(x,y,'x'); pyplot.axis('equal'); pyplot.show()
+
+Note that the covariance matrix must be non-negative definite.
+
+References
+----------
+.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
+       Processes," 3rd ed., McGraw-Hill Companies, 1991
+.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
+       2nd ed., Wiley, 2001.
+
+Examples
+--------
+>>> mean = (1,2)
+>>> cov = [[1,0],[1,0]]
+>>> x = multivariate_normal(mean,cov,(3,3))
+>>> x.shape
+(3, 3, 2)
+
+The following is probably true, given that 0.6 is roughly twice the
+standard deviation:
+
+>>> print list( (x[0,0,:] - mean) < 0.6 )
+[True, True]
+
+.. index:
+   :refguide: random:distributions