# [Scipy-svn] r4944 - in trunk/scipy: optimize spatial

scipy-svn@scip... scipy-svn@scip...
Sun Nov 2 22:53:39 CST 2008

```Author: damian.eads
Date: 2008-11-02 22:53:36 -0600 (Sun, 02 Nov 2008)
New Revision: 4944

Modified:
trunk/scipy/optimize/optimize.py
trunk/scipy/spatial/distance.py
trunk/scipy/spatial/info.py
Log:
Working on doc fixes.

Modified: trunk/scipy/optimize/optimize.py
===================================================================
--- trunk/scipy/optimize/optimize.py	2008-11-03 03:54:26 UTC (rev 4943)
+++ trunk/scipy/optimize/optimize.py	2008-11-03 04:53:36 UTC (rev 4944)
@@ -101,7 +101,7 @@
full_output=0, disp=1, retall=0, callback=None):
"""Minimize a function using the downhill simplex algorithm.

-    *Parameters*:
+    :Parameters:

func : callable func(x,*args)
The objective function to be minimized.
@@ -113,7 +113,7 @@
Called after each iteration, as callback(xk), where xk is the
current parameter vector.

-    *Returns*: (xopt, {fopt, iter, funcalls, warnflag})
+    :Returns: (xopt, {fopt, iter, funcalls, warnflag})

xopt : ndarray
Parameter that minimizes function.
@@ -146,7 +146,7 @@
retall : bool
Set to True to return list of solutions at each iteration.

-    *Notes*
+    :Notes:

Uses a Nelder-Mead simplex algorithm to find the minimum of
function of one or more variables.
@@ -406,7 +406,7 @@
args=(), c1=1e-4, c2=0.9, amax=50):
"""Find alpha that satisfies strong Wolfe conditions.

-    *Parameters*:
+    :Parameters:

f : callable f(x,*args)
Objective function.
@@ -426,7 +426,7 @@
c2 : float
Parameter for curvature condition rule.

-    *Returns*:
+    :Returns:

alpha0 : float
Alpha for which ``x_new = x0 + alpha * pk``.
@@ -435,7 +435,7 @@
gc : int

-    *Notes*
+    :Notes:

Uses the line search algorithm to enforce strong Wolfe
conditions.  See Wright and Nocedal, 'Numerical Optimization',
@@ -550,7 +550,7 @@
Uses the interpolation algorithm (Armiijo backtracking) as suggested by
Wright and Nocedal in 'Numerical Optimization', 1999, pg. 56-57

-    *Returns*: (alpha, fc, gc)
+    :Returns: (alpha, fc, gc)

"""

@@ -627,7 +627,7 @@
retall=0, callback=None):
"""Minimize a function using the BFGS algorithm.

-    *Parameters*:
+    :Parameters:

f : callable f(x,*args)
Objective function to be minimized.
@@ -648,7 +648,7 @@
iteration.  Called as callback(xk), where xk is the
current parameter vector.

-    *Returns*: (xopt, {fopt, gopt, Hopt, func_calls, grad_calls, warnflag}, <allvecs>)
+    :Returns: (xopt, {fopt, gopt, Hopt, func_calls, grad_calls, warnflag}, <allvecs>)

xopt : ndarray
Parameters which minimize f, i.e. f(xopt) == fopt.
@@ -679,7 +679,7 @@
retall : bool
Return a list of results at each iteration if True.

-    *Notes*
+    :Notes:

Optimize the function, f, whose gradient is given by fprime
using the quasi-Newton method of Broyden, Fletcher, Goldfarb,
@@ -801,7 +801,7 @@
maxiter=None, full_output=0, disp=1, retall=0, callback=None):
"""Minimize a function using a nonlinear conjugate gradient algorithm.

-    *Parameters*:
+    :Parameters:
f : callable f(x,*args)
Objective function to be minimized.
x0 : ndarray
@@ -822,7 +822,7 @@
iteration.  Called as callback(xk), where xk is the
current parameter vector.

-    *Returns*: (xopt, {fopt, func_calls, grad_calls, warnflag}, {allvecs})
+    :Returns: (xopt, {fopt, func_calls, grad_calls, warnflag}, {allvecs})

xopt : ndarray
Parameters which minimize f, i.e. f(xopt) == fopt.
@@ -850,7 +850,7 @@
retall : bool
return a list of results at each iteration if True.

-    *Notes*
+    :Notes:

Optimize the function, f, whose gradient is given by fprime
using the nonlinear conjugate gradient algorithm of Polak and
@@ -955,7 +955,7 @@
callback=None):
"""Minimize a function using the Newton-CG method.

-    *Parameters*:
+    :Parameters:

f : callable f(x,*args)
Objective function to be minimized.
@@ -979,7 +979,7 @@
each iteration.  Called as callback(xk), where xk is the
current parameter vector.

-    *Returns*: (xopt, {fopt, fcalls, gcalls, hcalls, warnflag},{allvecs})
+    :Returns: (xopt, {fopt, fcalls, gcalls, hcalls, warnflag},{allvecs})

xopt : ndarray
Parameters which minimizer f, i.e. ``f(xopt) == fopt``.
@@ -1011,7 +1011,7 @@
retall : bool
If True, return a list of results at each iteration.

-    *Notes*
+    :Notes:
1. scikits.openopt offers a unified syntax to call this and other solvers.
2. Only one of `fhess_p` or `fhess` need to be given.  If `fhess`
is provided, then `fhess_p` will be ignored.  If neither `fhess`
@@ -1132,7 +1132,7 @@
full_output=0, disp=1):
"""Bounded minimization for scalar functions.

-    *Parameters*:
+    :Parameters:

func : callable f(x,*args)
Objective function to be minimized (must accept and return scalars).
@@ -1154,7 +1154,7 @@
3 : print iteration results.

-    *Returns*: (xopt, {fval, ierr, numfunc})
+    :Returns: (xopt, {fval, ierr, numfunc})

xopt : ndarray
Parameters (over given interval) which minimize the
@@ -1168,7 +1168,7 @@
The number of function calls made.

-    *Notes*
+    :Notes:

Finds a local minimizer of the scalar function `func` in the
interval x1 < xopt < x2 using Brent's method.  (See `brent`
@@ -1429,7 +1429,7 @@
return the minimum of the function isolated to a fractional precision of
tol.

-    *Parameters*:
+    :Parameters:

func : callable f(x,*args)
Objective function.
@@ -1445,7 +1445,7 @@
If True, return all output args (xmin, fval, iter,
funcalls).

-    *Returns*:
+    :Returns:

xmin : ndarray
Optimum point.
@@ -1477,7 +1477,7 @@
return the minimum of the function isolated to a fractional precision of
tol.

-    *Parameters*:
+    :Parameters:

func : callable func(x,*args)
Objective function to minimize.
@@ -1494,7 +1494,7 @@
full_output : bool
If True, return optional outputs.

-    *Notes*
+    :Notes:

Uses analog of bisection method to decrease the bracketed
interval.
@@ -1557,7 +1557,7 @@
f(xa) > f(xb) < f(xc). It doesn't always mean that obtained
solution will satisfy xa<=x<=xb

-    *Parameters*:
+    :Parameters:

func : callable f(x,*args)
Objective function to minimize.
@@ -1570,7 +1570,7 @@
maxiter : int
Maximum number of iterations to perform.

-    *Returns*: xa, xb, xc, fa, fb, fc, funcalls
+    :Returns: xa, xb, xc, fa, fb, fc, funcalls

xa, xb, xc : float
Bracket.
@@ -1655,7 +1655,7 @@
direc=None):
"""Minimize a function using modified Powell's method.

-    *Parameters*:
+    :Parameters:

func : callable f(x,*args)
Objective function to be minimized.
@@ -1670,7 +1670,7 @@
direc : ndarray
Initial direction set.

-    *Returns*: (xopt, {fopt, xi, direc, iter, funcalls, warnflag}, {allvecs})
+    :Returns: (xopt, {fopt, xi, direc, iter, funcalls, warnflag}, {allvecs})

xopt : ndarray
Parameter which minimizes `func`.
@@ -1708,7 +1708,7 @@
If True, return a list of the solution at each iteration.

-    *Notes*
+    :Notes:

Uses a modification of Powell's method to find the minimum of
a function of N variables.
@@ -1825,9 +1825,9 @@
def brute(func, ranges, args=(), Ns=20, full_output=0, finish=fmin):
"""Minimize a function over a given range by brute force.

-    *Parameters*:
+    :Parameters:

-        func : callable f(x,*args)
+        func : callable ``f(x,*args)``
Objective function to be minimized.
ranges : tuple
Each element is a tuple of parameters or a slice object to
@@ -1839,7 +1839,7 @@
full_output : bool
If True, return the evaluation grid.

-    *Returns*: (x0, fval, {grid, Jout})
+    :Returns: (x0, fval, {grid, Jout})

x0 : ndarray
Value of arguments to `func`, giving minimum over the grid.
@@ -1851,7 +1851,7 @@
Jout : ndarray
Function values over grid:  ``Jout = func(*grid)``.

-    *Notes*
+    :Notes:

Find the minimum of a function evaluated on a grid given by
the tuple ranges.

Modified: trunk/scipy/spatial/distance.py
===================================================================
--- trunk/scipy/spatial/distance.py	2008-11-03 03:54:26 UTC (rev 4943)
+++ trunk/scipy/spatial/distance.py	2008-11-03 04:53:36 UTC (rev 4944)
@@ -1563,48 +1563,19 @@
thrown if ``XA`` and ``XB`` do not have the same number of
columns.

-    A rectangular distance matrix Y is returned. For each :math:`\$i\$`
+    A rectangular distance matrix ``Y`` is returned. For each :math:`\$i\$`
and :math:`\$j\$`, the metric ``dist(u=XA[i], v=XB[j])`` is computed
and stored in the :math:`\$ij\$`th entry.

-
-    :Parameters:
-       XA : ndarray
-           An :math:`\$m_A\$` by :math:`\$n\$` array of :math:`\$m_A\$`
-           original observations in an :math:`\$n\$`-dimensional space.
-       XB : ndarray
-           An :math:`\$m_B\$` by :math:`\$n\$` array of :math:`\$m_B\$`
-           original observations in an :math:`\$n\$`-dimensional space.
-       metric : string or function
-           The distance metric to use. The distance function can
-           be 'braycurtis', 'canberra', 'chebyshev', 'cityblock',
-           'correlation', 'cosine', 'dice', 'euclidean', 'hamming',
-           'jaccard', 'kulsinski', 'mahalanobis', 'matching',
-           'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean',
-           'sokalmichener', 'sokalsneath', 'sqeuclidean', 'wminkowski',
-           'yule'.
-       w : ndarray
-           The weight vector (for weighted Minkowski).
-       p : double
-           The p-norm to apply (for Minkowski, weighted and unweighted)
-       V : ndarray
-           The variance vector (for standardized Euclidean).
-       VI : ndarray
-           The inverse of the covariance matrix (for Mahalanobis).
-
-
-    :Returns:
-       Y : ndarray
-           A :math:`\$m_A\$` by :math:`\$m_B\$` distance matrix.
-
Calling Conventions
-------------------

1. ``Y = cdist(X, 'euclidean')``

-       Computes the distance between m points using Euclidean distance
-       (2-norm) as the distance metric between the points. The points
-       are arranged as m n-dimensional row vectors in the matrix X.
+       Computes the distance between :math:`\$m\$` points using
+       Euclidean distance (2-norm) as the distance metric between the
+       points. The points are arranged as :math:`\$m\$`
+       :math:`\$n\$`-dimensional row vectors in the matrix X.

2. ``Y = cdist(X, 'minkowski', p)``

@@ -1781,6 +1752,34 @@

dm = cdist(X, 'sokalsneath')

+    :Parameters:
+       XA : ndarray
+           An :math:`\$m_A\$` by :math:`\$n\$` array of :math:`\$m_A\$`
+           original observations in an :math:`\$n\$`-dimensional space.
+       XB : ndarray
+           An :math:`\$m_B\$` by :math:`\$n\$` array of :math:`\$m_B\$`
+           original observations in an :math:`\$n\$`-dimensional space.
+       metric : string or function
+           The distance metric to use. The distance function can
+           be 'braycurtis', 'canberra', 'chebyshev', 'cityblock',
+           'correlation', 'cosine', 'dice', 'euclidean', 'hamming',
+           'jaccard', 'kulsinski', 'mahalanobis', 'matching',
+           'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean',
+           'sokalmichener', 'sokalsneath', 'sqeuclidean', 'wminkowski',
+           'yule'.
+       w : ndarray
+           The weight vector (for weighted Minkowski).
+       p : double
+           The p-norm to apply (for Minkowski, weighted and unweighted)
+       V : ndarray
+           The variance vector (for standardized Euclidean).
+       VI : ndarray
+           The inverse of the covariance matrix (for Mahalanobis).
+
+
+    :Returns:
+       Y : ndarray
+           A :math:`\$m_A\$` by :math:`\$m_B\$` distance matrix.
"""

Modified: trunk/scipy/spatial/info.py
===================================================================
--- trunk/scipy/spatial/info.py	2008-11-03 03:54:26 UTC (rev 4943)
+++ trunk/scipy/spatial/info.py	2008-11-03 04:53:36 UTC (rev 4944)
@@ -1,21 +1,4 @@
"""
-Vector Quantization / Kmeans
-============================
-
-    Clustering algorithms are useful in information theory, target detection,
-    communications, compression, and other areas. The vq module only
-    supports vector quantization and the k-means algorithms. Development
-    of self-organizing maps (SOM) and other approaches is underway.
-
-Hierarchical Clustering
-=======================
-
-    The hierarchy module provides functions for hierarchical and agglomerative
-    clustering. Its features include generating hierarchical clusters from
-    distance matrices, computing distance matrices from observation vectors,
-    calculating statistics on clusters, cutting linkages to generate flat
-    clusters, and visualizing clusters with dendrograms.
-
Distance Computation
====================

```