[Scipy-svn] r5302 - in trunk: doc/source scipy/fftpack scipy/stats

scipy-svn@scip... scipy-svn@scip...
Tue Dec 30 17:30:46 CST 2008


Author: ptvirtan
Date: 2008-12-30 17:30:23 -0600 (Tue, 30 Dec 2008)
New Revision: 5302

Modified:
   trunk/doc/source/interpolate.rst
   trunk/doc/source/optimize.rst
   trunk/doc/source/special.rst
   trunk/doc/source/stats.mstats.rst
   trunk/doc/source/stats.rst
   trunk/scipy/fftpack/basic.py
   trunk/scipy/stats/distributions.py
   trunk/scipy/stats/info.py
   trunk/scipy/stats/stats.py
Log:
Merge from doc wiki

Modified: trunk/doc/source/interpolate.rst
===================================================================
--- trunk/doc/source/interpolate.rst	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/doc/source/interpolate.rst	2008-12-30 23:30:23 UTC (rev 5302)
@@ -39,6 +39,20 @@
    InterpolatedUnivariateSpline
    LSQUnivariateSpline
 
+The above univariate spline classes have the following methods:
+
+.. autosummary::
+   :toctree: generated/
+
+   UnivariateSpline.__call__
+   UnivariateSpline.derivatives
+   UnivariateSpline.integral
+   UnivariateSpline.roots
+   UnivariateSpline.get_coeffs
+   UnivariateSpline.get_knots
+   UnivariateSpline.get_residual
+   UnivariateSpline.set_smoothing_factor
+
 Low-level interface to FITPACK functions:
 
 .. autosummary::

Modified: trunk/doc/source/optimize.rst
===================================================================
--- trunk/doc/source/optimize.rst	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/doc/source/optimize.rst	2008-12-30 23:30:23 UTC (rev 5302)
@@ -30,6 +30,7 @@
    fmin_l_bfgs_b
    fmin_tnc
    fmin_cobyla
+   nnls
 
 Global
 ------

Modified: trunk/doc/source/special.rst
===================================================================
--- trunk/doc/source/special.rst	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/doc/source/special.rst	2008-12-30 23:30:23 UTC (rev 5302)
@@ -299,8 +299,18 @@
 weights, and total weights for the appropriate form of Gaussian
 quadrature.  These are returned in an n x 3 array with roots in
 the first column, weights in the second column, and total weights
-in the final column
+in the final column.
 
+.. warning::
+
+   Evaluating large-order polynomials using these functions can be
+   numerically unstable.
+
+   The reason is that the functions below return polynomials as
+   `numpy.poly1d` objects, which represent the polynomial in terms
+   of their coefficients, and this can result to loss of precision
+   when the polynomial terms are summed.
+
 .. autosummary::
    :toctree: generated/
 

Modified: trunk/doc/source/stats.mstats.rst
===================================================================
--- trunk/doc/source/stats.mstats.rst	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/doc/source/stats.mstats.rst	2008-12-30 23:30:23 UTC (rev 5302)
@@ -14,69 +14,68 @@
 .. autosummary::
    :toctree: generated/
 
-
-argstoarray
-betai
-chisquare
-count_tied_groups
-describe
-f_oneway
-f_value_wilks_lambda
-find_repeats
-friedmanchisquare
-gmean
-hmean
-kendalltau
-kendalltau_seasonal
-kruskalwallis
-kruskalwallis
-ks_twosamp
-ks_twosamp
-kurtosis
-kurtosistest
-linregress
-mannwhitneyu
-plotting_positions
-mode
-moment
-mquantiles
-msign
-normaltest
-obrientransform
-pearsonr
-plotting_positions
-pointbiserialr
-rankdata
-samplestd
-samplevar
-scoreatpercentile
-sem
-signaltonoise
-skew
-skewtest
-spearmanr
-std
-stderr
-theilslopes
-threshold
-tmax
-tmean
-tmin
-trim
-trima
-trimboth
-trimmed_stde
-trimr
-trimtail
-tsem
-ttest_onesamp
-ttest_ind
-ttest_onesamp
-ttest_rel
-tvar
-var
-variation
-winsorize
-z
-zmap
-zs
+   argstoarray
+   betai
+   chisquare
+   count_tied_groups
+   describe
+   f_oneway
+   f_value_wilks_lambda
+   find_repeats
+   friedmanchisquare
+   gmean
+   hmean
+   kendalltau
+   kendalltau_seasonal
+   kruskalwallis
+   kruskalwallis
+   ks_twosamp
+   ks_twosamp
+   kurtosis
+   kurtosistest
+   linregress
+   mannwhitneyu
+   plotting_positions
+   mode
+   moment
+   mquantiles
+   msign
+   normaltest
+   obrientransform
+   pearsonr
+   plotting_positions
+   pointbiserialr
+   rankdata
+   samplestd
+   samplevar
+   scoreatpercentile
+   sem
+   signaltonoise
+   skew
+   skewtest
+   spearmanr
+   std
+   stderr
+   theilslopes
+   threshold
+   tmax
+   tmean
+   tmin
+   trim
+   trima
+   trimboth
+   trimmed_stde
+   trimr
+   trimtail
+   tsem
+   ttest_onesamp
+   ttest_ind
+   ttest_onesamp
+   ttest_rel
+   tvar
+   var
+   variation
+   winsorize
+   z
+   zmap
+   zs

Modified: trunk/doc/source/stats.rst
===================================================================
--- trunk/doc/source/stats.rst	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/doc/source/stats.rst	2008-12-30 23:30:23 UTC (rev 5302)
@@ -143,6 +143,9 @@
 Statistical functions
 =====================
 
+Several of these functions have a similar version in scipy.stats.mstats
+which work for masked arrays.
+
 .. autosummary::
    :toctree: generated/
 
@@ -261,6 +264,13 @@
    ppcc_max
    ppcc_plot
 
+Univariate and multivariate kernel density estimation (:mod:`scipy.stats.kde`)
+==============================================================================
 
+.. autosummary::
+   :toctree: generated/
+
+   gaussian_kde
+
 For many more stat related functions install the software R and the
 interface package rpy.

Modified: trunk/scipy/fftpack/basic.py
===================================================================
--- trunk/scipy/fftpack/basic.py	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/scipy/fftpack/basic.py	2008-12-30 23:30:23 UTC (rev 5302)
@@ -55,31 +55,53 @@
 
 
 def fft(x, n=None, axis=-1, overwrite_x=0):
-    """ fft(x, n=None, axis=-1, overwrite_x=0) -> y
-
+    """
     Return discrete Fourier transform of arbitrary type sequence x.
 
-    The returned complex array contains
-      [y(0),y(1),..,y(n/2-1),y(-n/2),...,y(-1)]        if n is even
-      [y(0),y(1),..,y((n-1)/2),y(-(n-1)/2),...,y(-1)]  if n is odd
-    where
-      y(j) = sum[k=0..n-1] x[k] * exp(-sqrt(-1)*j*k* 2*pi/n)
-      j = 0..n-1
-    Note that y(-j) = y(n-j).
-
-    Optional input:
-      n
-        Defines the length of the Fourier transform. If n is not
-        specified then n=x.shape[axis] is set. If n<x.shape[axis],
+    Parameters
+    ----------
+    x : array-like
+        array to fourier transform.
+    n : int, optional
+        Length of the Fourier transform. If n<x.shape[axis],
         x is truncated. If n>x.shape[axis], x is zero-padded.
-      axis
-        The transform is applied along the given axis of the input
-        array (or the newly constructed array if n argument was used).
-      overwrite_x
-        If set to true, the contents of x can be destroyed.
+        (Default n=x.shape[axis]).
+    axis : int, optional
+        Axis along which the fft's are computed. (default=-1)
+    overwrite_x : bool, optional
+        If True the contents of x can be destroyed. (default=False)
 
-    Notes:
-      y == fft(ifft(y)) within numerical accuracy.
+    Returns
+    -------
+    z : complex ndarray
+        with the elements:
+            [y(0),y(1),..,y(n/2-1),y(-n/2),...,y(-1)]        if n is even
+            [y(0),y(1),..,y((n-1)/2),y(-(n-1)/2),...,y(-1)]  if n is odd
+        where
+            y(j) = sum[k=0..n-1] x[k] * exp(-sqrt(-1)*j*k* 2*pi/n), j = 0..n-1
+        Note that y(-j) = y(n-j).
+
+    See Also
+    --------
+    ifft : Inverse FFT
+    rfft : FFT of a real sequence
+
+    Notes
+    -----
+    The packing of the result is "standard": If A = fft(a, n), then A[0]
+    contains the zero-frequency term, A[1:n/2+1] contains the
+    positive-frequency terms, and A[n/2+1:] contains the negative-frequency
+    terms, in order of decreasingly negative frequency. So for an 8-point
+    transform, the frequencies of the result are [ 0, 1, 2, 3, 4, -3, -2, -1].
+
+    This is most efficient for n a power of two.
+
+    Examples
+    --------
+    >>> x = np.arange(5)
+    >>> np.all(np.abs(x-fft(ifft(x))<1.e-15) #within numerical accuracy.
+    True
+
     """
     tmp = asarray(x)
     if istype(tmp, numpy.complex128):

Modified: trunk/scipy/stats/distributions.py
===================================================================
--- trunk/scipy/stats/distributions.py	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/scipy/stats/distributions.py	2008-12-30 23:30:23 UTC (rev 5302)
@@ -275,18 +275,26 @@
     # These are actually called, and should not be overwritten if you
     # want to keep error checking.
     def rvs(self,*args,**kwds):
-        """Random variates of given type.
+        """
+        Random variates of given type.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
+        size : int or tuple of ints, optional
+            defining number of random variates (default=1)
 
-        **kwds
-        ======
-        size  - number of random variates (default=1)
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        rvs : array-like
+            random variates of given `size`
+
         """
         kwd_names = ['loc', 'scale', 'size', 'discrete']
         loc, scale, size, discrete = map(kwds.get, kwd_names,
@@ -322,18 +330,17 @@
 
 
 class rv_continuous(rv_generic):
-    """A Generic continuous random variable.
+    """
+    A Generic continuous random variable.
 
-    Continuous random variables are defined from a standard form chosen
-    for simplicity of representation.  The standard form may require
-    some shape parameters to complete its specification.  The distributions
-    also take optional location and scale parameters using loc= and scale=
-    keywords (defaults: loc=0, scale=1)
+    Continuous random variables are defined from a standard form and may
+    require some shape parameters to complete its specification.  Any
+    optional keyword parameters can be passed to the methods of the RV
+    object as given below:
 
-    These shape, scale, and location parameters can be passed to any of the
-    methods of the RV object such as the following:
-
-    generic.rvs(<shape(s)>,loc=0,scale=1)
+    Methods
+    -------
+    generic.rvs(<shape(s)>,loc=0,scale=1,size=1)
         - random variates
 
     generic.pdf(x,<shape(s)>,loc=0,scale=1)
@@ -352,18 +359,60 @@
         - inverse survival function (inverse of sf)
 
     generic.stats(<shape(s)>,loc=0,scale=1,moments='mv')
-        - mean('m',axis=0), variance('v'), skew('s'), and/or kurtosis('k')
+        - mean('m'), variance('v'), skew('s'), and/or kurtosis('k')
 
     generic.entropy(<shape(s)>,loc=0,scale=1)
         - (differential) entropy of the RV.
 
-    Alternatively, the object may be called (as a function) to fix
-       the shape, location, and scale parameters returning a
-       "frozen" continuous RV object:
+    generic.fit(data,<shape(s)>,loc=0,scale=1)
+        - Parameter estimates for generic data
 
-    myrv = generic(<shape(s)>,loc=0,scale=1)
-        - frozen RV object with the same methods but holding the
-            given shape, location, and scale fixed
+    Alternatively, the object may be called (as a function) to fix the shape,
+    location, and scale parameters returning a "frozen" continuous RV object:
+
+    rv = generic(<shape(s)>,loc=0,scale=1)
+        - frozen RV object with the same methods but holding the given shape, location, and scale fixed
+
+    Parameters
+    ----------
+    x : array-like
+        quantiles
+    q : array-like
+        lower or upper tail probability
+    <shape(s)> : array-like
+        shape parameters
+    loc : array-like, optional
+        location parameter (default=0)
+    scale : array-like, optional
+        scale parameter (default=1)
+    size : int or tuple of ints, optional
+        shape of random variates (default computed from input arguments )
+    moments : string, optional
+        composed of letters ['mvsk'] specifying which moments to compute where
+        'm' = mean, 'v' = variance, 's' = (Fisher's) skew and
+        'k' = (Fisher's) kurtosis. (default='mv')
+
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> numargs = generic.numargs
+    >>> [ <shape(s)> ] = [0.9,]*numargs
+    >>> rv = generic(<shape(s)>)
+
+    Display frozen pdf
+
+    >>> x = np.linspace(0,np.minimum(rv.dist.b,3))
+    >>> h=plt.plot(x,rv.pdf(x))
+
+    Check accuracy of cdf and ppf
+
+    >>> prb = generic.cdf(x,<shape(s)>)
+    >>> h=plt.semilogy(np.abs(x-generic.ppf(prb,c))+1e-20)
+
+    Random number generation
+
+    >>> R = generic.rvs(<shape(s)>,size=100)
+
     """
     def __init__(self, momtype=1, a=None, b=None, xa=-10.0, xb=10.0,
                  xtol=1e-14, badvalue=None, name=None, longname=None,
@@ -496,17 +545,26 @@
         return self.generic_moment(n,*args)
 
     def pdf(self,x,*args,**kwds):
-        """Probability density function at x of the given RV.
+        """
+        Probability density function at x of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        x : array-like
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        pdf : array-like
+            Probability density function evaluated at x
+
         """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
@@ -526,17 +584,26 @@
         return output
 
     def cdf(self,x,*args,**kwds):
-        """Cumulative distribution function at x of the given RV.
+        """
+        Cumulative distribution function at x of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        x : array-like
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        cdf : array-like
+            Cumulative distribution function evaluated at x
+
         """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
@@ -558,17 +625,26 @@
         return output
 
     def sf(self,x,*args,**kwds):
-        """Survival function (1-cdf) at x of the given RV.
+        """
+        Survival function (1-cdf) at x of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        x : array-like
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        sf : array-like
+            Survival function evaluated at x
+
         """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
@@ -589,17 +665,26 @@
         return output
 
     def ppf(self,q,*args,**kwds):
-        """Percent point function (inverse of cdf) at q of the given RV.
+        """
+        Percent point function (inverse of cdf) at q of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        q : array-like
+            lower tail probability
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        x : array-like
+            quantile corresponding to the lower tail probability q.
+
         """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
@@ -621,17 +706,26 @@
         return output
 
     def isf(self,q,*args,**kwds):
-        """Inverse survival function at q of the given RV.
+        """
+        Inverse survival function at q of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        q : array-like
+            upper tail probability
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
-        scale - scale parameter (default=1)
+        Returns
+        -------
+        x : array-like
+            quantile corresponding to the upper tail probability q.
+
         """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
@@ -654,23 +748,32 @@
         return output
 
     def stats(self,*args,**kwds):
-        """Some statistics of the given RV
+        """
+        Some statistics of the given RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
 
-        **kwds
-        ======
-        loc     - location parameter (default=0)
-        scale   - scale parameter (default=1)
-        moments - a string composed of letters ['mvsk'] specifying
-                   which moments to compute (default='mv')
-                   'm' = mean,
-                   'v' = variance,
-                   's' = (Fisher's) skew,
-                   'k' = (Fisher's) kurtosis.
+        moments : string, optional
+            composed of letters ['mvsk'] defining which moments to compute:
+            'm' = mean,
+            'v' = variance,
+            's' = (Fisher's) skew,
+            'k' = (Fisher's) kurtosis.
+            (default='mv')
+
+        Returns
+        -------
+        stats : sequence
+            of requested moments.
+
         """
         loc,scale,moments=map(kwds.get,['loc','scale','moments'])
 
@@ -767,13 +870,15 @@
             return tuple(output)
 
     def moment(self, n, *args):
-        """n'th non-central moment of distribution
+        """
+        n'th order non-central moment of distribution
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
         n: int, n>=1
+            order of moment
 
-        *args:
+        arg1, arg2, arg3,... : array-like
             The shape parameter(s) for the distribution (see docstring of the
             instance object for more information)
 
@@ -883,6 +988,21 @@
 
 
     def entropy(self, *args, **kwds):
+        """
+        Differential entropy of the RV.
+
+
+        Parameters
+        ----------
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        scale : array-like, optional
+            scale parameter (default=1)
+
+        """
         loc,scale=map(kwds.get,['loc','scale'])
         args, loc, scale = self._fix_loc_scale(args, loc, scale)
         args = tuple(map(arr,args))
@@ -3501,15 +3621,16 @@
 #  x_k, p(x_k) lists in initialization
 
 class rv_discrete(rv_generic):
-    """A generic discrete random variable.
+    """
+    A Generic discrete random variable.
 
-    Discrete random variables are defined from a standard form.
-    The standard form may require some other parameters to complete
-    its specification.  The distribution methods also take an optional location
-    parameter using loc= keyword.  The default is loc=0.  The calling form
-    of the methods follow:
+    Discrete random variables are defined from a standard form and may require
+    some shape parameters to complete its specification. Any optional keyword
+    parameters can be passed to the methods of the RV object as given below:
 
-    generic.rvs(<shape(s)>,loc=0)
+    Methods
+    -------
+    generic.rvs(<shape(s)>,loc=0,size=1)
         - random variates
 
     generic.pmf(x,<shape(s)>,loc=0)
@@ -3534,17 +3655,40 @@
         - entropy of the RV
 
     Alternatively, the object may be called (as a function) to fix
-       the shape and location parameters returning a
-       "frozen" discrete RV object:
+    the shape and location parameters returning a
+    "frozen" discrete RV object:
 
     myrv = generic(<shape(s)>,loc=0)
-        - frozen RV object with the same methods but holding the
-            given shape and location fixed.
+        - frozen RV object with the same methods but holding the given shape and location fixed.
 
     You can construct an aribtrary discrete rv where P{X=xk} = pk
     by passing to the rv_discrete initialization method (through the values=
     keyword) a tuple of sequences (xk,pk) which describes only those values of
     X (xk) that occur with nonzero probability (pk).
+
+    Examples:
+    ---------
+        >>> import matplotlib.pyplot as plt
+        >>> numargs = generic.numargs
+        >>> [ <shape(s)> ] = ['Replace with resonable value',]*numargs
+
+    Display frozen pmf:
+        >>> rv = generic(<shape(s)>)
+        >>> x = np.arange(0,np.min(rv.dist.b,3)+1)
+        >>> h = plt.plot(x,rv.pmf(x))
+
+    Check accuracy of cdf and ppf:
+        >>> prb = generic.cdf(x,<shape(s)>)
+        >>> h = plt.semilogy(np.abs(x-generic.ppf(prb,<shape(s)>))+1e-20)
+
+    Random number generation:
+        >>> R = generic.rvs(<shape(s)>,size=100)
+
+    Custom made discrete distribution:
+        >>> vals = [arange(7),(0.1,0.2,0.3,0.1,0.1,0.1,0.1)]
+        >>> custm = rv_discrete(name='custm',values=vals)
+        >>> h = plt.plot(vals[0],custm.pmf(vals[0]))
+
     """
     def __init__(self, a=0, b=inf, name=None, badvalue=None,
                  moment_tol=1e-8,values=None,inc=1,longname=None,
@@ -3676,20 +3820,48 @@
 
 
     def rvs(self, *args, **kwargs):
+        """
+        Random variates of given type.
+
+        Parameters
+        ----------
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        size : int or tuple of ints, optional
+            defining number of random variates (default=1)
+
+        Returns
+        -------
+        rvs : array-like
+            random variates of given `size`
+
+        """
         kwargs['discrete'] = True
         return rv_generic.rvs(self, *args, **kwargs)
 
     def pmf(self, k,*args, **kwds):
-        """Probability mass function at k of the given RV.
+        """
+        Probability mass function at k of the given RV.
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
+        Parameters
+        ----------
+        k : array-like
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+
+        Returns
+        -------
+        pmf : array-like
+            Probability mass function evaluated at k
+
         """
         loc = kwds.get('loc')
         args, loc = self._fix_loc(args, loc)
@@ -3708,16 +3880,24 @@
         return output
 
     def cdf(self, k, *args, **kwds):
-        """Cumulative distribution function at k of the given RV
+        """
+        Cumulative distribution function at k of the given RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        k : array-like, int
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
+        Returns
+        -------
+        cdf : array-like
+            Cumulative distribution function evaluated at k
+
         """
         loc = kwds.get('loc')
         args, loc = self._fix_loc(args, loc)
@@ -3740,16 +3920,24 @@
         return output
 
     def sf(self,k,*args,**kwds):
-        """Survival function (1-cdf) at k of the given RV
+        """
+        Survival function (1-cdf) at k of the given RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        k : array-like
+            quantiles
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
+        Returns
+        -------
+        sf : array-like
+            Survival function evaluated at k
+
         """
         loc= kwds.get('loc')
         args, loc = self._fix_loc(args, loc)
@@ -3770,16 +3958,24 @@
         return output
 
     def ppf(self,q,*args,**kwds):
-        """Percent point function (inverse of cdf) at q of the given RV
+        """
+        Percent point function (inverse of cdf) at q of the given RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        q : array-like
+            lower tail probability
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
+        Returns
+        -------
+        k : array-like
+            quantile corresponding to the lower tail probability, q.
+
         """
         loc = kwds.get('loc')
         args, loc = self._fix_loc(args, loc)
@@ -3803,16 +3999,24 @@
         return output
 
     def isf(self,q,*args,**kwds):
-        """Inverse survival function (1-sf) at q of the given RV
+        """
+        Inverse survival function (1-sf) at q of the given RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        q : array-like
+            upper tail probability
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
 
-        **kwds
-        ======
-        loc   - location parameter (default=0)
+        Returns
+        -------
+        k : array-like
+            quantile corresponding to the upper tail probability, q.
+
         """
 
         loc = kwds.get('loc')
@@ -3847,22 +4051,29 @@
         return output
 
     def stats(self, *args, **kwds):
-        """Some statistics of the given discrete RV
+        """
+        Some statistics of the given discrete RV
 
-        *args
-        =====
-        The shape parameter(s) for the distribution (see docstring of the
-           instance object for more information)
+        Parameters
+        ----------
+        arg1, arg2, arg3,... : array-like
+            The shape parameter(s) for the distribution (see docstring of the
+            instance object for more information)
+        loc : array-like, optional
+            location parameter (default=0)
+        moments : string, optional
+            composed of letters ['mvsk'] defining which moments to compute:
+            'm' = mean,
+            'v' = variance,
+            's' = (Fisher's) skew,
+            'k' = (Fisher's) kurtosis.
+            (default='mv')
 
-        **kwds
-        ======
-        loc     - location parameter (default=0)
-        moments - a string composed of letters ['mvsk'] specifying
-                   which moments to compute (default='mv')
-                   'm' = mean,
-                   'v' = variance,
-                   's' = (Fisher's) skew,
-                   'k' = (Fisher's) kurtosis.
+        Returns
+        -------
+        stats : sequence
+            of requested moments.
+
         """
         loc,moments=map(kwds.get,['loc','moments'])
         N = len(args)
@@ -3949,14 +4160,14 @@
             return tuple(output)
 
     def moment(self, n, *args, **kwds):   # Non-central moments in standard form.
-        """n'th non-central moment of the distribution
+        """
+        n'th non-central moment of the distribution
 
-
-        Parameters:
-        -----------
+        Parameters
+        ----------
         n: int, n>=1
-
-        *args:
+            order of moment
+        arg1, arg2, arg3,...: array-like
             The shape parameter(s) for the distribution (see docstring of the
             instance object for more information)
 

Modified: trunk/scipy/stats/info.py
===================================================================
--- trunk/scipy/stats/info.py	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/scipy/stats/info.py	2008-12-30 23:30:23 UTC (rev 5302)
@@ -9,213 +9,247 @@
 For each given name the following methods are available.  See docstring for
 rv_continuous for more information
 
-rvs   --  random variates with the distribution
-pdf   --  probability density function
-cdf   --  cummulative distribution function
-sf    --  survival function (1.0 - cdf)
-ppf   --  percent-point function (inverse of cdf)
-isf   --  inverse survival function
-stats --  mean, variance, and optionally skew and kurtosis
+:rvs:
+   random variates with the distribution
+:pdf:
+   probability density function
+:cdf:
+   cumulative distribution function
+:sf:
+   survival function (1.0 - cdf)
+:ppf:
+   percent-point function (inverse of cdf)
+:isf:
+   inverse survival function
+:stats:
+   mean, variance, and optionally skew and kurtosis
 
 Calling the instance as a function returns a frozen pdf whose shape,
 location, and scale parameters are fixed.
 
+Distributions
+---------------
+
 The distributions available with the above methods are:
 
-CONTINUOUS  (Total == 81 distributions)
-===========
-norm            --  Normal (Gaussian)
-alpha           --  Alpha
-anglit          --  Anglit
-arcsine         --  Arcsine
-beta            --  Beta
-betaprime       --  Beta Prime
-bradford        --  Bradford
-burr            --  Burr
-fisk            --  Fisk
-cauchy          --  Cauchy
-chi             --  Chi
-chi2            --  Chi-squared
-cosine          --  Cosine
-dgamma          --  Double Gamma
-dweibull        --  Double Weibull
-erlang          --  Erlang
-expon           --  Exponential
-exponweib       --  Exponentiated Weibull
-exponpow        --  Exponential Power
-fatiguelife     --  Fatigue Life (Birnbaum-Sanders)
-foldcauchy      --  Folded Cauchy
-f               --  F (Snecdor F)
-foldnorm        --  Folded Normal
-frechet_r       --  Frechet Right Sided, Extreme Value Type II (Extreme LB) or weibull_min
-frechet_l       --  Frechet Left Sided, Weibull_max
-genlogistic     --  Generalized Logistic
-genpareto       --  Generalized Pareto
-genexpon        --  Generalized Exponential
-genextreme      --  Generalized Extreme Value
-gausshyper      --  Gauss Hypergeometric
-gamma           --  Gamma
-gengamma        --  Generalized gamma
-genhalflogistic --  Generalized Half Logistic
-gompertz        --  Gompertz (Truncated Gumbel)
-gumbel_r        --  Right Sided Gumbel, Log-Weibull, Fisher-Tippett, Extreme Value Type I
-gumbel_l        --  Left Sided Gumbel, etc.
-halfcauchy      --  Half Cauchy
-halflogistic    --  Half Logistic
-halfnorm        --  Half Normal
-hypsecant       --  Hyperbolic Secant
-invgamma        --  Inverse Gamma
-invnorm         --  Inverse Normal
-invweibull      --  Inverse Weibull
-johnsonsb       --  Johnson SB
-johnsonsu       --  Johnson SU
-laplace         --  Laplace
-logistic        --  Logistic
-loggamma        --  Log-Gamma
-loglaplace      --  Log-Laplace (Log Double Exponential)
-lognorm         --  Log-Normal
-gilbrat         --  Gilbrat
-lomax           --  Lomax (Pareto of the second kind)
-maxwell         --  Maxwell
-mielke          --  Mielke's Beta-Kappa
-nakagami        --  Nakagami
-ncx2            --  Non-central chi-squared
-ncf             --  Non-central F
-t               --  Student's T
-nct             --  Non-central Student's T
-pareto          --  Pareto
-powerlaw        --  Power-function
-powerlognorm    --  Power log normal
-powernorm       --  Power normal
-rdist           --  R distribution
-reciprocal      --  Reciprocal
-rayleigh        --  Rayleigh
-rice            --  Rice
-recipinvgauss   --  Reciprocal Inverse Gaussian
-semicircular    --  Semicircular
-triang          --  Triangular
-truncexpon      --  Truncated Exponential
-truncnorm       --  Truncated Normal
-tukeylambda     --  Tukey-Lambda
-uniform         --  Uniform
-von_mises       --  Von-Mises (Circular)
-wald            --  Wald
-weibull_min     --  Minimum Weibull (see Frechet)
-weibull_max     --  Maximum Weibull (see Frechet)
-wrapcauchy      --  Wrapped Cauchy
-ksone           --  Kolmogorov-Smirnov one-sided (no stats)
-kstwobign       --  Kolmogorov-Smirnov two-sided test for Large N (no stats)
+=============== ==============================================================
+Continuous  (Total == 81 distributions)
+==============================================================================
+norm              Normal (Gaussian)
+alpha             Alpha
+anglit            Anglit
+arcsine           Arcsine
+beta              Beta
+betaprime         Beta Prime
+bradford          Bradford
+burr              Burr
+fisk              Fisk
+cauchy            Cauchy
+chi               Chi
+chi2              Chi-squared
+cosine            Cosine
+dgamma            Double Gamma
+dweibull          Double Weibull
+erlang            Erlang
+expon             Exponential
+exponweib         Exponentiated Weibull
+exponpow          Exponential Power
+fatiguelife       Fatigue Life (Birnbaum-Sanders)
+foldcauchy        Folded Cauchy
+f                 F (Snecdor F)
+foldnorm          Folded Normal
+frechet_r         Frechet Right Sided, Extreme Value Type II (Extreme LB) or weibull_min
+frechet_l         Frechet Left Sided, Weibull_max
+genlogistic       Generalized Logistic
+genpareto         Generalized Pareto
+genexpon          Generalized Exponential
+genextreme        Generalized Extreme Value
+gausshyper        Gauss Hypergeometric
+gamma             Gamma
+gengamma          Generalized gamma
+genhalflogistic   Generalized Half Logistic
+gompertz          Gompertz (Truncated Gumbel)
+gumbel_r          Right Sided Gumbel, Log-Weibull, Fisher-Tippett, Extreme Value Type I
+gumbel_l          Left Sided Gumbel, etc.
+halfcauchy        Half Cauchy
+halflogistic      Half Logistic
+halfnorm          Half Normal
+hypsecant         Hyperbolic Secant
+invgamma          Inverse Gamma
+invnorm           Inverse Normal
+invweibull        Inverse Weibull
+johnsonsb         Johnson SB
+johnsonsu         Johnson SU
+laplace           Laplace
+logistic          Logistic
+loggamma          Log-Gamma
+loglaplace        Log-Laplace (Log Double Exponential)
+lognorm           Log-Normal
+gilbrat           Gilbrat
+lomax             Lomax (Pareto of the second kind)
+maxwell           Maxwell
+mielke            Mielke's Beta-Kappa
+nakagami          Nakagami
+ncx2              Non-central chi-squared
+ncf               Non-central F
+t                 Student's T
+nct               Non-central Student's T
+pareto            Pareto
+powerlaw          Power-function
+powerlognorm      Power log normal
+powernorm         Power normal
+rdist             R distribution
+reciprocal        Reciprocal
+rayleigh          Rayleigh
+rice              Rice
+recipinvgauss     Reciprocal Inverse Gaussian
+semicircular      Semicircular
+triang            Triangular
+truncexpon        Truncated Exponential
+truncnorm         Truncated Normal
+tukeylambda       Tukey-Lambda
+uniform           Uniform
+von_mises         Von-Mises (Circular)
+wald              Wald
+weibull_min       Minimum Weibull (see Frechet)
+weibull_max       Maximum Weibull (see Frechet)
+wrapcauchy        Wrapped Cauchy
+ksone             Kolmogorov-Smirnov one-sided (no stats)
+kstwobign         Kolmogorov-Smirnov two-sided test for Large N (no stats)
+=============== ==============================================================
 
 
-DISCRETE    (Total == 10 distributions)
-============
-binom           --  Binomial
-bernoulli       --  Bernoulli
-nbinom          --  Negative Binomial
-geom            --  Geometric
-hypergeom       --  Hypergeometric
-logser          --  Logarithmic (Log-Series, Series)
-poisson         --  Poisson
-planck          --  Planck (Discrete Exponential)
-boltzmann       --  Boltzmann (Truncated Discrete Exponential)
-randint         --  Discrete Uniform
-zipf            --  Zipf
-dlaplace        --  Discrete Laplacian
+=============== ==============================================================
+Discrete    (Total == 10 distributions)
+==============================================================================
+binom             Binomial
+bernoulli         Bernoulli
+nbinom            Negative Binomial
+geom              Geometric
+hypergeom         Hypergeometric
+logser            Logarithmic (Log-Series, Series)
+poisson           Poisson
+planck            Planck (Discrete Exponential)
+boltzmann         Boltzmann (Truncated Discrete Exponential)
+randint           Discrete Uniform
+zipf              Zipf
+dlaplace          Discrete Laplacian
+=============== ==============================================================
 
 Statistical Functions (adapted from Gary Strangman)
+-----------------------------------------------------
 
-gmean           --  _
-hmean           --  _
-mean            --  _
-cmedian         --  _
-median          --  _
-mode            --  _
-tmean           --  _
-tvar            --  _
-tmin            --  _
-tmax            --  _
-tstd            --  _
-tsem            --  _
-moment          --  _
-variation       --  _
-skew            --  _
-kurtosis        --  _
-describe        --  _
-skewtest        --  _
-kurtosistest    --  _
-normaltest      --  _
+================= ==============================================================
+gmean             Geometric mean
+hmean             Harmonic mean
+mean              Arithmetic mean
+cmedian           Computed median
+median            Median
+mode              Modal value
+tmean             Truncated arithmetic mean
+tvar              Truncated variance
+tmin              _
+tmax              _
+tstd              _
+tsem              _
+moment            Central moment
+variation         Coefficient of variation
+skew              Skewness
+kurtosis          Fisher or Pearson kurtosis
+describe          Descriptive statistics
+skewtest          _
+kurtosistest      _
+normaltest        _
+================= ==============================================================
 
-itemfreq            -- _
-scoreatpercentile   -- _
-percentileofscore   -- _
-histogram2   -- _
-histogram   -- _
-cumfreq   -- _
-relfreq   -- _
+================= ==============================================================
+itemfreq          _
+scoreatpercentile _
+percentileofscore _
+histogram2        _
+histogram         _
+cumfreq           _
+relfreq           _
+================= ==============================================================
 
-obrientransform    -- _
-samplevar    -- _
-samplestd    -- _
-signaltonoise    -- _
-bayes_mvs   -- _
-var    -- _
-std    -- _
-stderr    -- _
-sem    -- _
-z    -- _
-zs    -- _
-zmap    -- _
+================= ==============================================================
+obrientransform   _
+samplevar         _
+samplestd         _
+signaltonoise     _
+bayes_mvs         _
+var               _
+std               _
+stderr            _
+sem               _
+z                 _
+zs                _
+zmap              _
+================= ==============================================================
 
-threshold    -- _
-trimboth    -- _
-trim1    -- _
-cov    -- _
-corrcoef    -- _
+================= ==============================================================
+threshold         _
+trimboth          _
+trim1             _
+cov               _
+corrcoef          _
+================= ==============================================================
 
-f_oneway    -- _
-paired    -- _
-pearsonr    -- _
-spearmanr    -- _
-pointbiserialr    -- _
-kendalltau    -- _
-linregress    -- _
+================= ==============================================================
+f_oneway          _
+paired            _
+pearsonr          _
+spearmanr         _
+pointbiserialr    _
+kendalltau        _
+linregress        _
+================= ==============================================================
 
-ttest_1samp    -- _
-ttest_ind    -- _
-ttest_rel    -- _
-kstest    -- _
-chisquare    -- _
-ks_2samp    -- _
-meanwhitneyu    -- _
-tiecorrect    -- _
-ranksums    -- _
-wilcoxon    -- _
-kruskal    -- _
-friedmanchisquare     -- _
+================= ==============================================================
+ttest_1samp       _
+ttest_ind         _
+ttest_rel         _
+kstest            _
+chisquare         _
+ks_2samp          _
+meanwhitneyu      _
+tiecorrect        _
+ranksums          _
+wilcoxon          _
+kruskal           _
+friedmanchisquare _
+================= ==============================================================
 
-ansari    -- _
-bartlett    -- _
-levene    -- _
-shapiro    -- _
-anderson    -- _
-binom_test    -- _
-fligner    -- _
-mood    -- _
-oneway    -- _
+================= ==============================================================
+ansari            _
+bartlett          _
+levene            _
+shapiro           _
+anderson          _
+binom_test        _
+fligner           _
+mood              _
+oneway            _
+================= ==============================================================
 
+================= ==============================================================
+glm               _
+anova             _
+================= ==============================================================
 
-glm    -- _
-anova  -- _
 
+================= ==============================================================
 Plot-tests
+================================================================================
+probplot          _
+ppcc_max          _
+ppcc_plot         _
+================= ==============================================================
 
-probplot    -- _
-ppcc_max    -- _
-ppcc_plot    -- _
 
-
 For many more stat related functions install the software R and the
 interface package rpy.
+
 """
 
 postpone_import = 1

Modified: trunk/scipy/stats/stats.py
===================================================================
--- trunk/scipy/stats/stats.py	2008-12-30 19:08:36 UTC (rev 5301)
+++ trunk/scipy/stats/stats.py	2008-12-30 23:30:23 UTC (rev 5302)
@@ -2136,7 +2136,8 @@
 #import scipy.stats
 #import distributions
 def kstest(rvs, cdf, args=(), N=20, alternative = 'two_sided', mode='approx',**kwds):
-    """Return the D-value and the p-value for a Kolmogorov-Smirnov test
+    """
+    Return the D-value and the p-value for a Kolmogorov-Smirnov test
 
     This performs a test of the distribution G(x) of an observed
     random variable against a given distribution F(x). Under the null
@@ -2151,14 +2152,12 @@
 
         array: 1-D observations of random variables
 
-        callable: function to generate random variables,
-                requires keyword argument `size`
+        callable: function to generate random variables, requires keyword
+        argument `size`
 
     cdf : string or callable
-        string: name of a distribution in scipy.stats
-        if rvs is a string then cdf can evaluate to False
-        or be the same as rvs
-
+        string: name of a distribution in scipy.stats, if rvs is a string then
+        cdf can evaluate to `False` or be the same as rvs
         callable: function to evaluate cdf
 
     args : tuple, sequence
@@ -2167,6 +2166,7 @@
         sample size if rvs is string or callable
     alternative : 'two_sided' (default), 'less' or 'greater'
         defines the alternative hypothesis (see explanation)
+
     mode : 'approx' (default) or 'asymp'
         defines the distribution used for calculating p-value
 
@@ -2205,8 +2205,7 @@
     >>> kstest(x,'norm')
     (0.44435602715924361, 0.038850142705171065)
 
-    >>> #fix random seed to get the same result
-    >>> np.random.seed(987654321)
+    >>> np.random.seed(987654321) # set random seed to get the same result
     >>> kstest('norm','',N=100)
     (0.058352892479417884, 0.88531190944151261)
 
@@ -2216,22 +2215,28 @@
     >>> kstest(stats.norm.rvs(size=100),'norm')
     (0.058352892479417884, 0.88531190944151261)
 
-    **test against one-sided alternative hypothesis**
+    Test against one-sided alternative hypothesis:
 
     >>> np.random.seed(987654321)
-    >>> #shift distribution to larger values, so that cdf_dgp(x)< norm.cdf(x)
-    >>> x = stats.norm.rvs(loc=0.2, size=100) 
-    >>> kstest(x,'norm', alternative = 'less') 
+
+    Shift distribution to larger values, so that cdf_dgp(x)< norm.cdf(x):
+
+    >>> x = stats.norm.rvs(loc=0.2, size=100)
+    >>> kstest(x,'norm', alternative = 'less')
     (0.12464329735846891, 0.040989164077641749)
-    >>> #reject equal distribution against alternative hypothesis: less
+
+    Reject equal distribution against alternative hypothesis: less
+
     >>> kstest(x,'norm', alternative = 'greater')
     (0.0072115233216311081, 0.98531158590396395)
-    >>> #don't reject equal distribution against alternative hypothesis: greater
+
+    Don't reject equal distribution against alternative hypothesis: greater
+
     >>> kstest(x,'norm', mode='asymp')
     (0.12464329735846891, 0.08944488871182088)
 
 
-    **testing t distributed random variables against normal distribution**
+    Testing t distributed random variables against normal distribution:
 
     With 100 degrees of freedom the t distribution looks close to the normal
     distribution, and the kstest does not reject the hypothesis that the sample



More information about the Scipy-svn mailing list