[Scipy-svn] r6409 - in trunk/scipy: linalg maxentropy sparse

[scipy-svn at scipy.org]

Author: rgommers
Date: 2010-05-24 08:11:58 -0500 (Mon, 24 May 2010)
New Revision: 6409

Modified:
   trunk/scipy/linalg/basic.py
   trunk/scipy/maxentropy/maxentropy.py
   trunk/scipy/sparse/dok.py
Log:
DOC: merge wiki edits - linalg, maxentropy and sparse.

Modified: trunk/scipy/linalg/basic.py
===================================================================
--- trunk/scipy/linalg/basic.py	2010-05-24 13:11:41 UTC (rev 6408)
+++ trunk/scipy/linalg/basic.py	2010-05-24 13:11:58 UTC (rev 6409)
@@ -292,38 +292,50 @@
 ### Linear Least Squares
 
 def lstsq(a, b, cond=None, overwrite_a=False, overwrite_b=False):
-    """Compute least-squares solution to equation :m:`a x = b`
+    """
+    Compute least-squares solution to equation Ax = b.
 
-    Compute a vector x such that the 2-norm :m:`|b - a x|` is minimised.
+    Compute a vector x such that the 2-norm ``|b - A x|`` is minimized.
 
     Parameters
     ----------
     a : array, shape (M, N)
+        Left hand side matrix (2-D array).
     b : array, shape (M,) or (M, K)
-    cond : float
+        Right hand side matrix or vector (1-D or 2-D array).
+    cond : float, optional
         Cutoff for 'small' singular values; used to determine effective
-        rank of a. Singular values smaller than rcond*largest_singular_value
-        are considered zero.
-    overwrite_a : boolean
-        Discard data in a (may enhance performance)
-    overwrite_b : boolean
-        Discard data in b (may enhance performance)
+        rank of a. Singular values smaller than
+        ``rcond * largest_singular_value`` are considered zero.
+    overwrite_a : bool, optional
+        Discard data in `a` (may enhance performance). Default is False.
+    overwrite_b : bool, optional
+        Discard data in `b` (may enhance performance). Default is False.
 
     Returns
     -------
     x : array, shape (N,) or (N, K) depending on shape of b
-        Least-squares solution
-    residues : array, shape () or (1,) or (K,)
-        Sums of residues, squared 2-norm for each column in :m:`b - a x`
+        Least-squares solution.
+    residues : ndarray, shape () or (1,) or (K,)
+        Sums of residues, squared 2-norm for each column in ``b - a x``.
         If rank of matrix a is < N or > M this is an empty array.
-        If b was 1-d, this is an (1,) shape array, otherwise the shape is (K,)
-    rank : integer
-        Effective rank of matrix a
+        If b was 1-D, this is an (1,) shape array, otherwise the shape is (K,).
+    rank : int
+        Effective rank of matrix `a`.
     s : array, shape (min(M,N),)
-        Singular values of a. The condition number of a is abs(s[0]/s[-1]).
+        Singular values of `a`. The condition number of a is
+        ``abs(s[0]/s[-1])``.
 
-    Raises LinAlgError if computation does not converge
+    Raises
+    ------
+    LinAlgError :
+        If computation does not converge.
 
+
+    See Also
+    --------
+    optimize.nnls : linear least squares with non-negativity constraint
+
     """
     a1, b1 = map(asarray_chkfinite, (a, b))
     if len(a1.shape) != 2:

Modified: trunk/scipy/maxentropy/maxentropy.py
===================================================================
--- trunk/scipy/maxentropy/maxentropy.py	2010-05-24 13:11:41 UTC (rev 6408)
+++ trunk/scipy/maxentropy/maxentropy.py	2010-05-24 13:11:58 UTC (rev 6409)
@@ -788,15 +788,16 @@
 
 
 class conditionalmodel(model):
-    """A conditional maximum-entropy (exponential-form) model p(x|w) on a
+    """
+    A conditional maximum-entropy (exponential-form) model p(x|w) on a
     discrete sample space.  This is useful for classification problems:
     given the context w, what is the probability of each class x?
 
-    The form of such a model is
+    The form of such a model is::
 
         p(x | w) = exp(theta . f(w, x)) / Z(w; theta)
 
-    where Z(w; theta) is a normalization term equal to
+    where Z(w; theta) is a normalization term equal to::
 
         Z(w; theta) = sum_x exp(theta . f(w, x)).
 
@@ -804,11 +805,11 @@
     the constructor as the parameter 'samplespace'.
 
     Such a model form arises from maximizing the entropy of a conditional
-    model p(x | w) subject to the constraints:
+    model p(x | w) subject to the constraints::
 
         K_i = E f_i(W, X)
 
-    where the expectation is with respect to the distribution
+    where the expectation is with respect to the distribution::
 
         q(w) p(x | w)
 
@@ -818,7 +819,7 @@
     x) with respect to the empirical distribution.
 
     This method minimizes the Lagrangian dual L of the entropy, which is
-    defined for conditional models as
+    defined for conditional models as::
 
         L(theta) = sum_w q(w) log Z(w; theta)
                    - sum_{w,x} q(w,x) [theta . f(w,x)]
@@ -827,8 +828,10 @@
     entire sample space, since q(w,x) = 0 for all w,x not in the training
     set.
 
-    The partial derivatives of L are:
+    The partial derivatives of L are::
+
         dL / dtheta_i = K_i - E f_i(X, Y)
+
     where the expectation is as defined above.
 
     """

Modified: trunk/scipy/sparse/dok.py
===================================================================
--- trunk/scipy/sparse/dok.py	2010-05-24 13:11:41 UTC (rev 6408)
+++ trunk/scipy/sparse/dok.py	2010-05-24 13:11:58 UTC (rev 6409)
@@ -13,12 +13,13 @@
 from sputils import isdense, getdtype, isshape, isintlike, isscalarlike, upcast
 
 class dok_matrix(spmatrix, dict):
-    """Dictionary Of Keys based sparse matrix.
+    """
+    Dictionary Of Keys based sparse matrix.
 
     This is an efficient structure for constructing sparse
     matrices incrementally.
 
-    This can be instatiated in several ways:
+    This can be instantiated in several ways:
         dok_matrix(D)
             with a dense matrix, D