Docstrings for ufunc methods add, reduce, outer, and the arcane reduceat.

1 files changed, 166 insertions, 4 deletions

diff --git a/numpy/core/src/ufuncobject.c b/numpy/core/src/ufuncobject.c
index e81967c7c..8e25ef6c5 100644
--- a/numpy/core/src/ufuncobject.c
+++ b/numpy/core/src/ufuncobject.c
@@ -3951,12 +3951,174 @@ ufunc_reduceat(PyUFuncObject *self, PyObject *args, PyObject *kwds)
 
 
 static struct PyMethodDef ufunc_methods[] = {
-    {"reduce",  (PyCFunction)ufunc_reduce, METH_VARARGS | METH_KEYWORDS},
+    {"reduce",  (PyCFunction)ufunc_reduce, METH_VARARGS | METH_KEYWORDS,
+        "reduce(array,axis=0,dtype=None,out=None)\n"
+        "reduce applies the operator to all elements of the array producing\n"
+        "a single result.\n" 
+        "\n" 
+        "For a one-dimensional array, reduce produces results equivalent to:\n"
+        "r = op.identity\n"
+        "for i in xrange(len(A)):\n"
+        "    r = op(r,A[i])\n"
+        "return r\n"
+        "\n"
+        "For example, add.reduce() is equivalent to sum().\n"
+        "\n"
+        "Parameters:\n"
+        "-----------\n"
+        "\n"
+        "array : array-like\n"
+        "    The array to act on.\n"
+        "axis : integer\n"
+        "    The axis along which to apply the reduction.\n"
+        "dtype : data type or None\n"
+        "    The type used to represent the intermediate results. Defaults\n"
+        "    to the data type of the output array if this is provided, or\n"
+        "    the data type of the input array if no output array is provided.\n"
+        "out : array-like or None\n"
+        "    A location into which the result is stored. If not provided a\n"
+        "    freshly-allocated array is returned.\n"
+        "\n"
+        "Returns:\n"
+        "--------\n"
+        "\n"
+        "r : array\n"
+        "    The reduced values. If out was supplied, r is equal to out.\n"
+        "\n"
+        "Example:\n"
+        "--------\n"
+        ">>> np.multiply.reduce([2,3,5])\n"
+        "30\n"
+        "\n"
+    },
     {"accumulate",  (PyCFunction)ufunc_accumulate,
-     METH_VARARGS | METH_KEYWORDS},
+     METH_VARARGS | METH_KEYWORDS,
+        "accumulate(array,axis=None,dtype=None,out=None)\n"
+        "accumulate applies the operator to all elements of the array producing\n"
+        "cumulative results.\n" 
+        "\n" 
+        "For a one-dimensional array, accumulate produces results equivalent to:\n"
+        "r = np.empty(len(A))\n"
+        "t = op.identity\n"
+        "for i in xrange(len(A)):\n"
+        "    t = op(t,A[i])\n"
+        "    r[i] = t\n"
+        "return r\n"
+        "\n"
+        "For example, add.accumulate() is equivalent to cumsum().\n"
+        "\n"
+        "Parameters:\n"
+        "-----------\n"
+        "\n"
+        "array : array-like\n"
+        "    The array to act on.\n"
+        "axis : integer\n"
+        "    The axis along which to apply the accumulation.\n"
+        "dtype : data type or None\n"
+        "    The type used to represent the intermediate results. Defaults\n"
+        "    to the data type of the output array if this is provided, or\n"
+        "    the data type of the input array if no output array is provided.\n"
+        "out : array-like or None\n"
+        "    A location into which the result is stored. If not provided a\n"
+        "    freshly-allocated array is returned.\n"
+        "\n"
+        "Returns:\n"
+        "--------\n"
+        "\n"
+        "r : array\n"
+        "    The accumulated values. If out was supplied, r is equal to out.\n"
+        "\n"
+        "Example:\n"
+        "--------\n"
+        ">>> np.multiply.accumulate([2,3,5])\n"
+        "array([2,6,30])\n"
+        "\n"
+    },
     {"reduceat",  (PyCFunction)ufunc_reduceat,
-     METH_VARARGS | METH_KEYWORDS},
-    {"outer", (PyCFunction)ufunc_outer, METH_VARARGS | METH_KEYWORDS},
+     METH_VARARGS | METH_KEYWORDS,
+        "reduceat(self,array,indices,axis=None,dtype=None,out=None)\n"
+        "reduceat performs a reduce over an axis using the indices as a guide\n"
+        "\n"
+        "op.reduceat(array,indices)  computes\n"
+        "op.reduce(array[indices[i]:indices[i+1]]\n"
+        "for i=0..end with an implicit indices[i+1]=len(array)\n"
+        "assumed when i=end-1\n"
+        "\n"
+        "if indices[i+1] <= indices[i]+1\n"
+        "then the result is array[indices[i]] for that value\n"
+        "\n"
+        "op.accumulate(array) is the same as\n"
+        "op.reduceat(array,indices)[::2]\n"
+        "where indices is range(len(array)-1) with a zero placed\n"
+        "in every other sample:\n"
+        "indices = zeros(len(array)*2-1)\n"
+        "indices[1::2] = range(1,len(array))\n"
+        "\n"
+        "output shape is based on the size of indices\n"
+        "\n"
+        "Parameters:\n"
+        "-----------\n"
+        "\n"
+        "array : array-like\n"
+        "    The array to act on.\n"
+        "indices : array-like\n"
+        "    Indices specifying ranges to reduce.\n"
+        "axis : integer\n"
+        "    The axis along which to apply the reduceat.\n"
+        "dtype : data type or None\n"
+        "    The type used to represent the intermediate results. Defaults\n"
+        "    to the data type of the output array if this is provided, or\n"
+        "    the data type of the input array if no output array is provided.\n"
+        "out : array-like or None\n"
+        "    A location into which the result is stored. If not provided a\n"
+        "    freshly-allocated array is returned.\n"
+        "\n"
+        "Returns:\n"
+        "--------\n"
+        "\n"
+        "r : array\n"
+        "    The reduced values. If out was supplied, r is equal to out.\n"
+        "\n"
+        "Example:\n"
+        "--------\n"
+        "To take the running sum of four successive values:\n"
+        ">>> np.multiply.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2]\n"
+        "array([ 6, 10, 14, 18])\n"
+        "\n"
+    },
+    {"outer", (PyCFunction)ufunc_outer, METH_VARARGS | METH_KEYWORDS,
+    "outer(A,B)\n"
+    "Compute the result of applying op to all pairs (a,b)\n"
+    "\n"
+    "op.outer(A,B) is equivalent to\n"
+    "op(A[:,:,...,:,newaxis,...,newaxis]*B[newaxis,...,newaxis,:,...,:]\n"
+    "where A has B.ndim new axes appended and B has A.ndim new axes prepended.\n"
+    "\n"
+    "For A and B one-dimensional, this is equivalent to\n"
+    "r = empty(len(A),len(B))\n"
+    "for i in xrange(len(A)):\n"
+    "    for j in xrange(len(B)):\n"
+    "        r[i,j] = A[i]*B[j]\n"
+    "If A and B are higher-dimensional, the result has dimension A.ndim+B.ndim\n"
+    "\n"
+    "Parameters:\n"
+    "-----------\n"
+    "\n"
+    "A : array-like\n"
+    "B : array-like\n"
+    "\n"
+    "Returns:\n"
+    "--------\n"
+    "\n"
+    "r : array\n"
+    "Example:\n"
+    "--------\n"
+    ">>> np.multiply.outer([1,2,3],[4,5,6])\n"
+    "array([[ 4,  5,  6],\n"
+    "       [ 8, 10, 12],\n"
+    "       [12, 15, 18]])\n"
+    "\n"
+    },
     {NULL,          NULL}           /* sentinel */
 };