diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.ndarray.rst | 37 | ||||
| -rw-r--r-- | doc/source/reference/arrays.scalars.rst | 4 | ||||
| -rw-r--r-- | doc/source/reference/c-api.generalized-ufuncs.rst (renamed from doc/source/reference/generalized_ufuncs.rst) | 10 | ||||
| -rw-r--r-- | doc/source/reference/c-api.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/c-api.ufunc.rst | 43 | ||||
| -rw-r--r-- | doc/source/reference/index.rst | 7 | ||||
| -rw-r--r-- | doc/source/reference/routines.statistics.rst | 1 |
7 files changed, 52 insertions, 51 deletions
diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 0def05ced..1bf7d1ac8 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -9,14 +9,14 @@ The N-dimensional array (:class:`ndarray`) An :class:`ndarray` is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its :attr:`shape <ndarray.shape>`, -which is a :class:`tuple` of *N* integers that specify the sizes of +which is a :class:`tuple` of *N* positive integers that specify the sizes of each dimension. The type of items in the array is specified by a separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which is associated with each ndarray. -As with other container objects in Python, the contents of a +As with other container objects in Python, the contents of an :class:`ndarray` can be accessed and modified by :ref:`indexing or -slicing <arrays.indexing>` the array (using for example *N* integers), +slicing <arrays.indexing>` the array (using, for example, *N* integers), and via the methods and attributes of the :class:`ndarray`. .. index:: view, base @@ -42,15 +42,19 @@ objects implementing the :class:`buffer` or :ref:`array >>> x.dtype dtype('int32') - The array can be indexed using a Python container-like syntax: + The array can be indexed using Python container-like syntax: - >>> x[1,2] + >>> x[1,2] # i.e., the element of x in the *second* row, *third* column 6 For example :ref:`slicing <arrays.indexing>` can produce views of the array: >>> y = x[:,1] - >>> y[0] = 9 + >>> y + array([2, 5]) + >>> y[0] = 9 # this also changes the corresponding element in x + >>> y + array([9, 5]) >>> x array([[1, 9, 3], [4, 5, 6]]) @@ -95,7 +99,7 @@ the bytes are interpreted is defined by the :ref:`data-type object .. index:: C-order, Fortran-order, row-major, column-major, stride, offset A segment of memory is inherently 1-dimensional, and there are many -different schemes of arranging the items of an *N*-dimensional array to +different schemes for arranging the items of an *N*-dimensional array in a 1-dimensional block. Numpy is flexible, and :class:`ndarray` objects can accommodate any *strided indexing scheme*. In a strided scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})` corresponds @@ -105,10 +109,10 @@ to the offset (in bytes) from the beginning of the memory block associated with the array. Here, :math:`s_k` are integers which specify the :obj:`strides -<ndarray.strides>` of the array. The :term:`column-major` order (used -for example in the Fortran language and in *Matlab*) and -:term:`row-major` order (used in C) are special cases of the strided -scheme, and correspond to the strides: +<ndarray.strides>` of the array. The :term:`column-major` order (used, +for example, in the Fortran language and in *Matlab*) and +:term:`row-major` order (used in C) schemes are just specific kinds of +strided scheme, and correspond to the strides: .. math:: @@ -116,12 +120,12 @@ scheme, and correspond to the strides: .. index:: single-segment, contiguous, non-contiguous -Both the C and Fortran orders are :term:`contiguous`, *i.e.* +Both the C and Fortran orders are :term:`contiguous`, *i.e.,* :term:`single-segment`, memory layouts, in which every part of the memory block can be accessed by some combination of the indices. Data in new :class:`ndarrays <ndarray>` is in the :term:`row-major` -(C) order, unless otherwise specified, but for example :ref:`basic +(C) order, unless otherwise specified, but, for example, :ref:`basic array slicing <arrays.indexing>` often produces :term:`views <view>` in a different scheme. @@ -227,7 +231,8 @@ Array methods An :class:`ndarray` object has many methods which operate on or with the array in some fashion, typically returning an array result. These -methods are explained below. +methods are briefly explained below. (Each method's doc string has a +more complete description.) For the following methods there are also corresponding functions in :mod:`numpy`: :func:`all`, :func:`any`, :func:`argmax`, @@ -433,7 +438,7 @@ Arithmetic: .. note:: - Any third argument to :func:`pow()` is silently ignored, - as the underlying :func:`ufunc <power>` only takes two arguments. + as the underlying :func:`ufunc <power>` takes only two arguments. - The three division operators are all defined; :obj:`div` is active by default, :obj:`truediv` is active when @@ -472,7 +477,7 @@ Arithmetic, in-place: the array. Therefore, for mixed precision calculations, ``A {op}= B`` can be different than ``A = A {op} B``. For example, suppose ``a = ones((3,3))``. Then, ``a += 3j`` is different than ``a = a + - 3j``: While they both perform the same computation, ``a += 3`` + 3j``: while they both perform the same computation, ``a += 3`` casts the result to fit back in ``a``, whereas ``a = a + 3j`` re-binds the name ``a`` to the result. diff --git a/doc/source/reference/arrays.scalars.rst b/doc/source/reference/arrays.scalars.rst index 33d5ceff6..75daf2a08 100644 --- a/doc/source/reference/arrays.scalars.rst +++ b/doc/source/reference/arrays.scalars.rst @@ -204,8 +204,6 @@ elements the data type consists of.) :mod:`struct` module. -.. note:: XXX: what to put in the type docstrings, and where to put them? - Attributes ========== @@ -235,7 +233,6 @@ attribute. Otherwise, they share the same attributes as arrays: generic.__array_priority__ generic.__array_wrap__ -.. note:: XXX: import the documentation into the docstrings? Indexing ======== @@ -273,7 +270,6 @@ The exceptions to the above rules are given below: generic.__setstate__ generic.setflags -.. note:: XXX: import the documentation into the docstrings? Defining new types ================== diff --git a/doc/source/reference/generalized_ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst index d9f3818b9..870e5dbc4 100644 --- a/doc/source/reference/generalized_ufuncs.rst +++ b/doc/source/reference/c-api.generalized-ufuncs.rst @@ -1,6 +1,6 @@ -=============================== -Generalized Universal Functions -=============================== +================================== +Generalized Universal Function API +================================== There is a general need for looping over not only functions on scalars but also over functions on vectors (or arrays), as explained on @@ -91,14 +91,14 @@ dimensions. The signature is represented by a string of the following format: * Core dimensions of each input or output array are represented by a - list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar + list of dimension names in parentheses, ``(i_1,...,i_N)``; a scalar input/output is denoted by ``()``. Instead of ``i_1``, ``i_2``, etc, one can use any valid Python variable name. * Dimension lists for different arguments are separated by ``","``. Input/output arguments are separated by ``"->"``. * If one uses the same dimension name in multiple locations, this enforces the same size (or broadcastable size) of the corresponding - dimensions. + dimensions. The formal syntax of signatures is as follows:: diff --git a/doc/source/reference/c-api.rst b/doc/source/reference/c-api.rst index 158e04a16..9bcc68b49 100644 --- a/doc/source/reference/c-api.rst +++ b/doc/source/reference/c-api.rst @@ -45,4 +45,5 @@ code. c-api.dtype c-api.array c-api.ufunc + c-api.generalized-ufuncs c-api.coremath diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index bd0ee8e02..6a6a0dff0 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -70,43 +70,45 @@ Functions operation. Each ufunc object contains pointers to 1-d loops implementing the basic functionality for each supported type. - :param nin: - - The number of inputs to this operation. - - :param nout: - - The number of outputs - - :param ntypes: + .. note:: - How many different data-type "signatures" the ufunc has implemented. + The *func*, *data*, *types*, *name*, and *doc* arguments are not + copied by :cfunc:`PyUFunc_FromFuncAndData`. The caller must ensure + that the memory used by these arrays is not freed as long as the + ufunc object is alive. :param func: - Must to an array of length *ntypes* containing :ctype:`PyUFuncGenericFunction` items. These items are pointers to - functions that acutally implement the underlying - (element-by-element) function :math:`N` times. T + functions that actually implement the underlying + (element-by-element) function :math:`N` times. - :param types: + :param data: + Should be ``NULL`` or a pointer to an array of size *ntypes* + . This array may contain arbitrary extra-data to be passed to + the corresponding 1-d loop function in the func array. + :param types: Must be of length (*nin* + *nout*) \* *ntypes*, and it contains the data-types (built-in only) that the corresponding function in the *func* array can deal with. - :param data: + :param ntypes: + How many different data-type "signatures" the ufunc has implemented. - Should be ``NULL`` or a pointer to an array of size *ntypes* - . This array may contain arbitrary extra-data to be passed to - the corresponding 1-d loop function in the func array. + :param nin: + The number of inputs to this operation. - :param name: + :param nout: + The number of outputs + :param identity: + XXX: Undocumented + + :param name: The name for the ufunc. :param doc: - Allows passing in a documentation string to be stored with the ufunc. The documentation string should not contain the name of the function or the calling signature as that will be @@ -114,7 +116,6 @@ Functions accessing the **__doc__** attribute of the ufunc. :param check_return: - Unused and present for backwards compatibility of the C-API. A corresponding *check_return* integer does exist in the ufunc structure and it does get set with this value when the ufunc diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 0d83053ac..00317a18e 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -19,7 +19,6 @@ For learning how to use NumPy, see also :ref:`user`. arrays ufuncs - generalized_ufuncs routines ctypes distutils @@ -37,8 +36,6 @@ the functions are written by numerous contributors and developers of Numpy, both prior to and during the `Numpy Documentation Marathon <http://scipy.org/Developer_Zone/DocMarathon2008>`__. -The Documentation Marathon is still ongoing. Please help us write -better documentation for Numpy by joining it! Instructions on how to -join and what to do can be found +Please help to improve NumPy's documentation! Instructions on how to +join the ongoing documentation marathon can be found `on the scipy.org website <http://scipy.org/Developer_Zone/DocMarathon2008>`__ - diff --git a/doc/source/reference/routines.statistics.rst b/doc/source/reference/routines.statistics.rst index b41b62839..578cbd09a 100644 --- a/doc/source/reference/routines.statistics.rst +++ b/doc/source/reference/routines.statistics.rst @@ -35,6 +35,7 @@ Correlating :toctree: generated/ corrcoef + acorrelate correlate cov |