diff options
| author | Jarrod Millman <millman@berkeley.edu> | 2010-02-17 23:55:16 +0000 |
|---|---|---|
| committer | Jarrod Millman <millman@berkeley.edu> | 2010-02-17 23:55:16 +0000 |
| commit | 1c7167378e9f654a80b3cb57b7c0dd7ee573a109 (patch) | |
| tree | 1926d178db2e66c19552f8216926c07155f7cde3 | |
| parent | e2bb09430d90c73a7be6e47ea8c4528f094f693f (diff) | |
| download | numpy-1c7167378e9f654a80b3cb57b7c0dd7ee573a109.tar.gz | |
updated documentation from pydoc website (thanks to everyone who contributed!)
25 files changed, 425 insertions, 336 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 51d97e53a..bef723091 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -13,8 +13,8 @@ difficult decision, and can be simply a matter of choice. NumPy has several tools for simplifying how your new object interacts with other array objects, and so the choice may not be significant in the end. One way to simplify the question is by asking yourself if the -object you are interested in can be replaced as a single array or does it -really require two or more arrays at its core. +object you are interested in can be replaced as a single array or does +it really require two or more arrays at its core. Note that :func:`asarray` always returns the base-class ndarray. If you are confident that your use of the array object can handle any @@ -42,10 +42,10 @@ customize: This method is called whenever the system internally allocates a new array from *obj*, where *obj* is a subclass (subtype) of the - :class:`ndarray`. It can be used to change attributes of *self* after - construction (so as to ensure a 2-d matrix for example), or to - update meta-information from the "parent." Subclasses inherit a - default implementation of this method that does nothing. + :class:`ndarray`. It can be used to change attributes of *self* + after construction (so as to ensure a 2-d matrix for example), or + to update meta-information from the "parent." Subclasses inherit + a default implementation of this method that does nothing. .. function:: __array_prepare__(array, context=None) @@ -66,10 +66,10 @@ customize: the output object if one was specified. The ufunc-computed array is passed in and whatever is returned is passed to the user. Subclasses inherit a default implementation of this method, which - transforms the array into a new instance of the object's class. Subclasses - may opt to use this method to transform the output array into an - instance of the subclass and update metadata before returning the - array to the user. + transforms the array into a new instance of the object's class. + Subclasses may opt to use this method to transform the output array + into an instance of the subclass and update metadata before + returning the array to the user. .. data:: __array_priority__ @@ -96,21 +96,21 @@ important differences of matrix objects, however, that may lead to unexpected results when you use matrices but expect them to act like arrays: -1. Matrix objects can be created using a string notation to allow Matlab- - style syntax where spaces separate columns and semicolons (';') - separate rows. +1. Matrix objects can be created using a string notation to allow + Matlab-style syntax where spaces separate columns and semicolons + (';') separate rows. 2. Matrix objects are always two-dimensional. This has far-reaching - implications, in that m.ravel() is still two-dimensional (with a 1 in - the first dimension) and item selection returns two-dimensional + implications, in that m.ravel() is still two-dimensional (with a 1 + in the first dimension) and item selection returns two-dimensional objects so that sequence behavior is fundamentally different than arrays. 3. Matrix objects over-ride multiplication to be matrix-multiplication. **Make sure you understand this for functions that you may want to receive matrices. Especially in - light of the fact that asanyarray(m) returns a matrix when m is a - matrix.** + light of the fact that asanyarray(m) returns a matrix when m is + a matrix.** 4. Matrix objects over-ride power to be matrix raised to a power. The same warning about using power inside a function that uses @@ -119,8 +119,8 @@ arrays: 5. The default __array_priority\__ of matrix objects is 10.0, and therefore mixed operations with ndarrays always produce matrices. -6. Matrices have special attributes which make calculations easier. These - are +6. Matrices have special attributes which make calculations easier. + These are .. autosummary:: :toctree: generated/ @@ -132,11 +132,12 @@ arrays: .. warning:: - Matrix objects over-ride multiplication, '*', and power, '**', to be - matrix-multiplication and matrix power, respectively. If your - subroutine can accept sub-classes and you do not convert to base-class - arrays, then you must use the ufuncs multiply and power to be sure - that you are performing the correct operation for all inputs. + Matrix objects over-ride multiplication, '*', and power, '**', to + be matrix-multiplication and matrix power, respectively. If your + subroutine can accept sub-classes and you do not convert to base- + class arrays, then you must use the ufuncs multiply and power to + be sure that you are performing the correct operation for all + inputs. The matrix class is a Python subclass of the ndarray and can be used as a reference for how to construct your own subclass of the ndarray. @@ -194,10 +195,10 @@ array actually get written to disk. .. note:: - Memory-mapped arrays use the the Python memory-map object which (prior - to Python 2.5) does not allow files to be larger than a certain size - depending on the platform. This size is always < 2GB even on 64-bit - systems. + Memory-mapped arrays use the the Python memory-map object which + (prior to Python 2.5) does not allow files to be larger than a + certain size depending on the platform. This size is always + < 2GB even on 64-bit systems. .. autosummary:: :toctree: generated/ @@ -228,10 +229,11 @@ Character arrays (:mod:`numpy.char`) single: character arrays .. note:: - The chararray module exists for backwards compatibility with - Numarray, it is not recommended for new development. If one needs - arrays of strings, use arrays of `dtype` `object_`, `str` or - `unicode`. + The `chararray` class exists for backwards compatibility with + Numarray, it is not recommended for new development. Starting from numpy + 1.4, if one needs arrays of strings, it is recommended to use arrays of + `dtype` `object_`, `string_` or `unicode_`, and use the free functions + in the `numpy.char` module for fast vectorized string operations. These are enhanced arrays of either :class:`string_` type or :class:`unicode_` type. These arrays inherit from the @@ -240,8 +242,8 @@ and ``%`` on a (broadcasting) element-by-element basis. These operations are not available on the standard :class:`ndarray` of character type. In addition, the :class:`chararray` has all of the standard :class:`string <str>` (and :class:`unicode`) methods, -executing them on an element-by-element basis. Perhaps the easiest way -to create a chararray is to use :meth:`self.view(chararray) +executing them on an element-by-element basis. Perhaps the easiest +way to create a chararray is to use :meth:`self.view(chararray) <ndarray.view>` where *self* is an ndarray of str or unicode data-type. However, a chararray can also be created using the :meth:`numpy.chararray` constructor, or via the @@ -255,8 +257,8 @@ data-type. However, a chararray can also be created using the Another difference with the standard ndarray of str data-type is that the chararray inherits the feature introduced by Numarray that -white-space at the end of any element in the array will be ignored on -item retrieval and comparison operations. +white-space at the end of any element in the array will be ignored +on item retrieval and comparison operations. .. _arrays.classes.rec: @@ -341,7 +343,8 @@ used as an iterator. The default behavior is equivalent to:: for i in arr.shape[0]: val = arr[i] -This default iterator selects a sub-array of dimension :math:`N-1` from the array. This can be a useful construct for defining recursive +This default iterator selects a sub-array of dimension :math:`N-1` +from the array. This can be a useful construct for defining recursive algorithms. To loop over the entire array requires :math:`N` for-loops. >>> a = arange(24).reshape(3,2,4)+10 diff --git a/doc/source/reference/arrays.dtypes.rst b/doc/source/reference/arrays.dtypes.rst index 4cc5a88d8..213168ac4 100644 --- a/doc/source/reference/arrays.dtypes.rst +++ b/doc/source/reference/arrays.dtypes.rst @@ -148,8 +148,8 @@ Array-scalar types .. admonition:: Example - >>> dt = np.dtype(np.int32) # 32-bit integer - >>> dt = np.dtype(np.complex128) # 128-bit complex floating-point number + >>> dt = np.dtype(np.int32) # 32-bit integer + >>> dt = np.dtype(np.complex128) # 128-bit complex floating-point number Generic types @@ -305,9 +305,9 @@ Type strings .. admonition:: Example - >>> dt = np.dtype((np.int32, (2,2))) # 2 x 2 integer sub-array - >>> dt = np.dtype(('S10', 1)) # 10-character string - >>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 record sub-array + >>> dt = np.dtype((np.int32, (2,2))) # 2 x 2 integer sub-array + >>> dt = np.dtype(('S10', 1)) # 10-character string + >>> dt = np.dtype(('i4, (2,3)f8, f4', (2,3))) # 2 x 3 record sub-array ``(base_dtype, new_dtype)`` @@ -321,7 +321,7 @@ Type strings 32-bit integer, whose first two bytes are interpreted as an integer via field ``real``, and the following two bytes via field ``imag``. - >>> dt = np.dtype((np.int32, {'real': (np.int16, 0), 'imag': (np.int16, 2)}) + >>> dt = np.dtype((np.int32,{'real':(np.int16, 0),'imag':(np.int16, 2)}) 32-bit integer, which is interpreted as consisting of a sub-array of shape ``(4,)`` containing 8-bit integers: @@ -333,8 +333,6 @@ Type strings >>> dt = np.dtype(('i4', [('r','u1'),('g','u1'),('b','u1'),('a','u1')])) -.. note:: XXX: does the second-to-last example above make sense? - .. index:: triple: dtype; construction; from list @@ -428,7 +426,8 @@ Type strings byte position 0), ``col2`` (32-bit float at byte position 10), and ``col3`` (integers at byte position 14): - >>> dt = np.dtype({'col1': ('S10', 0), 'col2': (float32, 10), 'col3': (int, 14)}) + >>> dt = np.dtype({'col1': ('S10', 0), 'col2': (float32, 10), + 'col3': (int, 14)}) :class:`dtype` diff --git a/doc/source/reference/arrays.indexing.rst b/doc/source/reference/arrays.indexing.rst index a47474922..8da4ecca7 100644 --- a/doc/source/reference/arrays.indexing.rst +++ b/doc/source/reference/arrays.indexing.rst @@ -318,13 +318,6 @@ done. Also recognize that ``x[[1,2,3]]`` will trigger advanced indexing, whereas ``x[[1,2,slice(None)]]`` will trigger basic slicing. -.. note:: - - XXX: this section may need some tuning... - Also the above warning needs explanation as the last part is at odds - with the definition of basic indexing. - - .. _arrays.indexing.rec: Record Access diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 0cad2ac6e..c14e6869a 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -9,9 +9,9 @@ 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* 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 +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 an @@ -32,7 +32,8 @@ objects implementing the :class:`buffer` or :ref:`array .. admonition:: Example - A 2-dimensional array of size 2 x 3, composed of 4-byte integer elements: + A 2-dimensional array of size 2 x 3, composed of 4-byte integer + elements: >>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32) >>> type(x) @@ -44,10 +45,11 @@ objects implementing the :class:`buffer` or :ref:`array The array can be indexed using Python container-like syntax: - >>> x[1,2] # i.e., the element of x in the *second* row, *third* column - 6 + >>> x[1,2] # i.e., the element of x in the *second* row, *third* + column, namely, 6. - For example :ref:`slicing <arrays.indexing>` can produce views of the array: + For example :ref:`slicing <arrays.indexing>` can produce views of + the array: >>> y = x[:,1] >>> y @@ -96,14 +98,15 @@ which the indices can vary is specified by the :obj:`shape the bytes are interpreted is defined by the :ref:`data-type object <arrays.dtypes>` associated with the array. -.. index:: C-order, Fortran-order, row-major, column-major, stride, offset +.. 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 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 -to the offset (in bytes) +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 to the offset (in bytes): .. math:: n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k @@ -116,7 +119,8 @@ strided scheme, and correspond to the strides: .. math:: - s_k^{\mathrm{column}} = \prod_{j=0}^{k-1} d_j , \quad s_k^{\mathrm{row}} = \prod_{j=k+1}^{N-1} d_j . + s_k^{\mathrm{column}} = \prod_{j=0}^{k-1} d_j , + \quad s_k^{\mathrm{row}} = \prod_{j=k+1}^{N-1} d_j . .. index:: single-segment, contiguous, non-contiguous @@ -172,8 +176,6 @@ of the array: ndarray.nbytes ndarray.base -.. note:: XXX: update and check these docstrings. - Data type --------- @@ -187,8 +189,6 @@ The data type object associated with the array can be found in the ndarray.dtype -.. note:: XXX: update the dtype attribute docstring: setting etc. - Other attributes ---------------- @@ -223,9 +223,6 @@ Array interface ndarray.ctypes -.. note:: XXX: update and check these docstrings. - - .. _array.ndarray.methods: Array methods @@ -241,11 +238,12 @@ For the following methods there are also corresponding functions in :func:`argmin`, :func:`argsort`, :func:`choose`, :func:`clip`, :func:`compress`, :func:`copy`, :func:`cumprod`, :func:`cumsum`, :func:`diagonal`, :func:`imag`, :func:`max <amax>`, :func:`mean`, -:func:`min <amin>`, :func:`nonzero`, :func:`prod`, :func:`ptp`, :func:`put`, -:func:`ravel`, :func:`real`, :func:`repeat`, :func:`reshape`, -:func:`round <around>`, :func:`searchsorted`, :func:`sort`, :func:`squeeze`, -:func:`std`, :func:`sum`, :func:`swapaxes`, :func:`take`, -:func:`trace`, :func:`transpose`, :func:`var`. +:func:`min <amin>`, :func:`nonzero`, :func:`prod`, :func:`ptp`, +:func:`put`, :func:`ravel`, :func:`real`, :func:`repeat`, +:func:`reshape`, :func:`round <around>`, :func:`searchsorted`, +:func:`sort`, :func:`squeeze`, :func:`std`, :func:`sum`, +:func:`swapaxes`, :func:`take`, :func:`trace`, :func:`transpose`, +:func:`var`. Array conversion ---------------- @@ -268,8 +266,6 @@ Array conversion ndarray.setflags ndarray.fill -.. note:: XXX: update and check these docstrings. - Shape manipulation ------------------ @@ -323,8 +319,8 @@ Many of these methods take an argument named *axis*. In such cases, float32, float64, etc., whereas a 0-dimensional array is an ndarray instance containing precisely one array scalar.) -- If *axis* is an integer, then the operation is done over the given axis - (for each 1-D subarray that can be created along the given axis). +- If *axis* is an integer, then the operation is done over the given + axis (for each 1-D subarray that can be created along the given axis). .. admonition:: Example of the *axis* argument @@ -393,9 +389,6 @@ be performed. Arithmetic and comparison operations ==================================== -.. note:: XXX: write all attributes explicitly here instead of relying on - the auto\* stuff? - .. index:: comparison, arithmetic, operation, operator Arithmetic and comparison operations on :class:`ndarrays <ndarray>` @@ -435,9 +428,9 @@ Truth value of an array (:func:`bool()`): :meth:`ndarray.__nonzero__`, which raises an error if the number of elements in the the array is larger than 1, because the truth value of such arrays is ambiguous. Use :meth:`.any() <ndarray.any>` and - :meth:`.all() <ndarray.all>` instead to be clear about what is meant in - such cases. (If the number of elements is 0, the array evaluates to - ``False``.) + :meth:`.all() <ndarray.all>` instead to be clear about what is meant + in such cases. (If the number of elements is 0, the array evaluates + to ``False``.) Unary operations: diff --git a/doc/source/reference/c-api.coremath.rst b/doc/source/reference/c-api.coremath.rst index 12d6f522d..5c50f36e4 100644 --- a/doc/source/reference/c-api.coremath.rst +++ b/doc/source/reference/c-api.coremath.rst @@ -125,7 +125,8 @@ precision are also available by adding the F and L suffixes respectively. .. cvar:: NPY_EULER - The Euler constant (:math:`\lim_{n\rightarrow \infty}{\sum_{k=1}^n{\frac{1}{k}} - \ln n}`) + The Euler constant + :math:`\lim_{n\rightarrow\infty}({\sum_{k=1}^n{\frac{1}{k}}-\ln n})` Low-level floating point manipulation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/reference/c-api.types-and-structures.rst b/doc/source/reference/c-api.types-and-structures.rst index 8fe698c9b..9b34890c1 100644 --- a/doc/source/reference/c-api.types-and-structures.rst +++ b/doc/source/reference/c-api.types-and-structures.rst @@ -416,7 +416,8 @@ PyArrayDescr_Type functions can (and must) deal with mis-behaved arrays. The other functions require behaved memory segments. - .. cmember:: void cast(void *from, void *to, npy_intp n, void *fromarr, void *toarr) + .. cmember:: void cast(void *from, void *to, npy_intp n, void *fromarr, + void *toarr) An array of function pointers to cast from the current type to all of the other builtin types. Each function casts a @@ -442,7 +443,8 @@ PyArrayDescr_Type a zero is returned, otherwise, a negative one is returned (and a Python error set). - .. cmember:: void copyswapn(void *dest, npy_intp dstride, void *src, npy_intp sstride, npy_intp n, int swap, void *arr) + .. cmember:: void copyswapn(void *dest, npy_intp dstride, void *src, + npy_intp sstride, npy_intp n, int swap, void *arr) .. cmember:: void copyswap(void *dest, void *src, int swap, void *arr) @@ -468,7 +470,8 @@ PyArrayDescr_Type ``d1`` < * ``d2``. The array object arr is used to retrieve itemsize and field information for flexible arrays. - .. cmember:: int argmax(void* data, npy_intp n, npy_intp* max_ind, void* arr) + .. cmember:: int argmax(void* data, npy_intp n, npy_intp* max_ind, + void* arr) A pointer to a function that retrieves the index of the largest of ``n`` elements in ``arr`` beginning at the element @@ -477,7 +480,8 @@ PyArrayDescr_Type always 0. The index of the largest element is returned in ``max_ind``. - .. cmember:: void dotfunc(void* ip1, npy_intp is1, void* ip2, npy_intp is2, void* op, npy_intp n, void* arr) + .. cmember:: void dotfunc(void* ip1, npy_intp is1, void* ip2, npy_intp is2, + void* op, npy_intp n, void* arr) A pointer to a function that multiplies two ``n`` -length sequences together, adds them, and places the result in @@ -527,7 +531,8 @@ PyArrayDescr_Type computed by repeatedly adding this computed delta. The data buffer must be well-behaved. - .. cmember:: void fillwithscalar(void* buffer, npy_intp length, void* value, void* arr) + .. cmember:: void fillwithscalar(void* buffer, npy_intp length, + void* value, void* arr) A pointer to a function that fills a contiguous ``buffer`` of the given ``length`` with a single scalar ``value`` whose @@ -542,7 +547,8 @@ PyArrayDescr_Type :cdata:`PyArray_MERGESORT` are defined). These sorts are done in-place assuming contiguous and aligned data. - .. cmember:: int argsort(void* start, npy_intp* result, npy_intp length, void \*arr) + .. cmember:: int argsort(void* start, npy_intp* result, npy_intp length, + void \*arr) An array of function pointers to sorting algorithms for this data type. The same sorting algorithms as for sort are @@ -666,11 +672,12 @@ PyUFunc_Type .. cmember:: int PyUFuncObject.identity - Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, or :cdata:`PyUFunc_None` - to indicate the identity for this operation. It is only used - for a reduce-like call on an empty array. + Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, or + :cdata:`PyUFunc_None` to indicate the identity for this operation. + It is only used for a reduce-like call on an empty array. - .. cmember:: void PyUFuncObject.functions(char** args, npy_intp* dims, npy_intp* steps, void* extradata) + .. cmember:: void PyUFuncObject.functions(char** args, npy_intp* dims, + npy_intp* steps, void* extradata) An array of function pointers --- one for each data type supported by the ufunc. This is the vector loop that is called @@ -764,8 +771,8 @@ PyArrayIter_Type .. ctype:: PyArrayIterObject The C-structure corresponding to an object of :cdata:`PyArrayIter_Type` is - the :ctype:`PyArrayIterObject`. The :ctype:`PyArrayIterObject` is used to keep - track of a pointer into an N-dimensional array. It contains associated + the :ctype:`PyArrayIterObject`. The :ctype:`PyArrayIterObject` is used to + keep track of a pointer into an N-dimensional array. It contains associated information used to quickly march through the array. The pointer can be adjusted in three basic ways: 1) advance to the "next" position in the array in a C-style contiguous fashion, 2) advance to an arbitrary @@ -928,8 +935,9 @@ PyArrayNeighborhoodIter_Type .. ctype:: PyArrayNeighborhoodIterObject - The C-structure corresponding to an object of :cdata:`PyArrayNeighborhoodIter_Type` is - the :ctype:`PyArrayNeighborhoodIterObject`. + The C-structure corresponding to an object of + :cdata:`PyArrayNeighborhoodIter_Type` is the + :ctype:`PyArrayNeighborhoodIterObject`. PyArrayFlags_Type ----------------- @@ -1183,4 +1191,3 @@ for completeness and assistance in understanding the code. ``arrayobject.h`` header. This type is not exposed to Python and could be replaced with a C-structure. As a Python type it takes advantage of reference- counted memory management. - diff --git a/doc/source/reference/c-api.ufunc.rst b/doc/source/reference/c-api.ufunc.rst index fc8b5b6b1..384a69cf7 100644 --- a/doc/source/reference/c-api.ufunc.rst +++ b/doc/source/reference/c-api.ufunc.rst @@ -63,7 +63,9 @@ Macros Functions --------- -.. cfunction:: PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return) +.. cfunction:: PyObject* PyUFunc_FromFuncAndData(PyUFuncGenericFunction* func, + void** data, char* types, int ntypes, int nin, int nout, int identity, + char* name, char* doc, int check_return) Create a new broadcasting universal function from required variables. Each ufunc builds around the notion of an element-by-element @@ -102,9 +104,6 @@ Functions :param nout: The number of outputs - :param identity: - XXX: Undocumented - :param name: The name for the ufunc. Specifying a name of 'add' or 'multiply' enables a special behavior for integer-typed @@ -127,7 +126,8 @@ Functions structure and it does get set with this value when the ufunc object is created. -.. cfunction:: int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) +.. cfunction:: int PyUFunc_RegisterLoopForType(PyUFuncObject* ufunc, + int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) This function allows the user to register a 1-d loop with an already- created ufunc to be used whenever the ufunc is called @@ -140,7 +140,9 @@ Functions in as *arg_types* which must be a pointer to memory at least as large as ufunc->nargs. -.. cfunction:: int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, PyUFuncGenericFunction newfunc, int* signature, PyUFuncGenericFunction* oldfunc) +.. cfunction:: int PyUFunc_ReplaceLoopBySignature(PyUFuncObject* ufunc, + PyUFuncGenericFunction newfunc, int* signature, + PyUFuncGenericFunction* oldfunc) Replace a 1-d loop matching the given *signature* in the already-created *ufunc* with the new 1-d loop newfunc. Return the @@ -150,7 +152,8 @@ Functions signature is an array of data-type numbers indicating the inputs followed by the outputs assumed by the 1-d loop. -.. cfunction:: int PyUFunc_GenericFunction(PyUFuncObject* self, PyObject* args, PyArrayObject** mps) +.. cfunction:: int PyUFunc_GenericFunction(PyUFuncObject* self, + PyObject* args, PyArrayObject** mps) A generic ufunc call. The ufunc is passed in as *self*, the arguments to the ufunc as *args*. The *mps* argument is an array @@ -179,7 +182,8 @@ Functions Clear the IEEE error flags. -.. cfunction:: void PyUFunc_GetPyValues(char* name, int* bufsize, int* errmask, PyObject** errobj) +.. cfunction:: void PyUFunc_GetPyValues(char* name, int* bufsize, + int* errmask, PyObject** errobj) Get the Python values used for ufunc processing from the thread-local storage area unless the defaults have been set in @@ -206,21 +210,29 @@ of these functions are suitable for placing directly in the array of functions stored in the functions member of the PyUFuncObject structure. -.. cfunction:: void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_f_f_As_d_d(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_d_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_d_d(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_f_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_f_f(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_g_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_g_g(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_F_F_As_D_D(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_F_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_F_F(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_D_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_D_D(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_G_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_G_G(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) Type specific, core 1-d functions for ufuncs where each calculation is obtained by calling a function taking one input @@ -235,21 +247,29 @@ structure. but calls out to a C-function that takes double and returns double. -.. cfunction:: void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_ff_f_As_dd_d(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_ff_f(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_ff_f(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_dd_d(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_dd_d(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_gg_g(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_gg_g(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_FF_F_As_DD_D(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_DD_D(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_DD_D(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_FF_F(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_FF_F(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_GG_G(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_GG_G(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) Type specific, core 1-d functions for ufuncs where each calculation is obtained by calling a function taking two input @@ -261,25 +281,29 @@ structure. of one data type but cast the values at each iteration of the loop to use the underlying function that takes a different data type. -.. cfunction:: void PyUFunc_O_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_O_O(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) -.. cfunction:: void PyUFunc_OO_O(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_OO_O(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) One-input, one-output, and two-input, one-output core 1-d functions - for the :cdata:`NPY_OBJECT` data type. These functions handle reference count - issues and return early on error. The actual function to call is *func* - and it must accept calls with the signature ``(PyObject*)(PyObject*)`` - for :cfunc:`PyUFunc_O_O` or ``(PyObject*)(PyObject *, PyObject *)`` - for :cfunc:`PyUFunc_OO_O`. + for the :cdata:`NPY_OBJECT` data type. These functions handle reference + count issues and return early on error. The actual function to call is + *func* and it must accept calls with the signature ``(PyObject*) + (PyObject*)`` for :cfunc:`PyUFunc_O_O` or ``(PyObject*)(PyObject *, + PyObject *)`` for :cfunc:`PyUFunc_OO_O`. -.. cfunction:: void PyUFunc_O_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_O_O_method(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) This general purpose 1-d core function assumes that *func* is a string representing a method of the input object. For each iteration of the loop, the Python obejct is extracted from the array and its *func* method is called returning the result to the output array. -.. cfunction:: void PyUFunc_OO_O_method(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_OO_O_method(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) This general purpose 1-d core function assumes that *func* is a string representing a method of the input object that takes one @@ -288,7 +312,8 @@ structure. function. The output of the function is stored in the third entry of *args*. -.. cfunction:: void PyUFunc_On_Om(char** args, npy_intp* dimensions, npy_intp* steps, void* func) +.. cfunction:: void PyUFunc_On_Om(char** args, npy_intp* dimensions, + npy_intp* steps, void* func) This is the 1-d core function used by the dynamic ufuncs created by umath.frompyfunc(function, nin, nout). In this case *func* is a diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst index 00317a18e..8074c24ba 100644 --- a/doc/source/reference/index.rst +++ b/doc/source/reference/index.rst @@ -34,7 +34,8 @@ Large parts of this manual originate from Travis E. Oliphant's book Public Domain in August 2008). The reference documentation for many of 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>`__. +`Numpy Documentation Marathon +<http://scipy.org/Developer_Zone/DocMarathon2008>`__. Please help to improve NumPy's documentation! Instructions on how to join the ongoing documentation marathon can be found diff --git a/doc/source/reference/internals.code-explanations.rst b/doc/source/reference/internals.code-explanations.rst index 7c1ab6ccb..cceb1a60d 100644 --- a/doc/source/reference/internals.code-explanations.rst +++ b/doc/source/reference/internals.code-explanations.rst @@ -99,7 +99,7 @@ have to create an iterator object from an ndarray, work with the dataptr member of the iterator object structure and call the macro :cfunc:`PyArray_ITER_NEXT` (it) on the iterator object to move to the next element. The "next" element is always in C-contiguous order. The macro -works by first special casing the C-contiguous, 1-d, and 2-d cases +works by first special casing the C-contiguous, 1-D, and 2-D cases which work very simply. For the general case, the iteration works by keeping track of a list @@ -196,7 +196,7 @@ Advanced ("Fancy") Indexing The implementation of advanced indexing represents some of the most difficult code to write and explain. In fact, there are two -implementations of advanced indexing. The first works only with 1-d +implementations of advanced indexing. The first works only with 1-D arrays and is implemented to handle expressions involving a.flat[obj]. The second is general-purpose that works for arrays of "arbitrary dimension" (up to a fixed maximum). The one-dimensional indexing @@ -222,7 +222,7 @@ because that is optimized by the Python interpreter itself. After these optimizations, the array_subscript function itself is called. This function first checks for field selection which occurs -when a string is passed as the indexing object. Then, 0-d arrays are +when a string is passed as the indexing object. Then, 0-D arrays are given special-case consideration. Finally, the code determines whether or not advanced, or fancy, indexing needs to be performed. If fancy indexing is not needed, then standard view-based indexing is performed @@ -330,12 +330,12 @@ Universal Functions single: ufunc Universal functions are callable objects that take :math:`N` inputs -and produce :math:`M` outputs by wrapping basic 1-d loops that work +and produce :math:`M` outputs by wrapping basic 1-D loops that work element-by-element into full easy-to use functions that seamlessly implement broadcasting, type-checking and buffered coercion, and output-argument handling. New universal functions are normally created in C, although there is a mechanism for creating ufuncs from Python -functions (:func:`frompyfunc`). The user must supply a 1-d loop that +functions (:func:`frompyfunc`). The user must supply a 1-D loop that implements the basic function taking the input scalar values and placing the resulting scalars into the appropriate output slots as explaine n implementation. @@ -349,7 +349,7 @@ the calculation. The practical significance of this overhead is that even though the actual calculation of the ufunc is very fast, you will be able to write array and type-specific code that will work faster for small arrays than the ufunc. In particular, using ufuncs to -perform many calculations on 0-d arrays will be slower than other +perform many calculations on 0-D arrays will be slower than other Python-based solutions (the silently-imported scalarmath module exists precisely to give array scalars the look-and-feel of ufunc-based calculations with significantly reduced overhead). @@ -366,9 +366,9 @@ The first thing done is to look-up in the thread-specific global dictionary the current values for the buffer-size, the error mask, and the associated error object. The state of the error mask controls what happens when an error-condiction is found. It should be noted that -checking of the hardware error flags is only performed after each 1-d +checking of the hardware error flags is only performed after each 1-D loop is executed. This means that if the input and output arrays are -contiguous and of the correct type so that a single 1-d loop is +contiguous and of the correct type so that a single 1-D loop is performed, then the flags may not be checked until all elements of the array have been calcluated. Looking up these values in a thread- specific dictionary takes time which is easily ignored for all but @@ -378,11 +378,11 @@ After checking, the thread-specific global variables, the inputs are evaluated to determine how the ufunc should proceed and the input and output arrays are constructed if necessary. Any inputs which are not arrays are converted to arrays (using context if necessary). Which of -the inputs are scalars (and therefore converted to 0-d arrays) is +the inputs are scalars (and therefore converted to 0-D arrays) is noted. -Next, an appropriate 1-d loop is selected from the 1-d loops available -to the ufunc based on the input array types. This 1-d loop is selected +Next, an appropriate 1-D loop is selected from the 1-D loops available +to the ufunc based on the input array types. This 1-D loop is selected by trying to match the signature of the data-types of the inputs against the available signatures. The signatures corresponding to built-in types are stored in the types member of the ufunc structure. @@ -394,10 +394,10 @@ The signatures are searched until a signature is found to which the input arrays can all be cast safely (ignoring any scalar arguments which are not allowed to determine the type of the result). The implication of this search procedure is that "lesser types" should be -placed below "larger types" when the signatures are stored. If no 1-d +placed below "larger types" when the signatures are stored. If no 1-D loop is found, then an error is reported. Otherwise, the argument_list is updated with the stored signature --- in case casting is necessary -and to fix the output types assumed by the 1-d loop. +and to fix the output types assumed by the 1-D loop. If the ufunc has 2 inputs and 1 output and the second input is an Object array then a special-case check is performed so that @@ -406,7 +406,7 @@ the __array_priority\__ attribute, and has an __r{op}\__ special method. In this way, Python is signaled to give the other object a chance to complete the operation instead of using generic object-array calculations. This allows (for example) sparse matrices to override -the multiplication operator 1-d loop. +the multiplication operator 1-D loop. For input arrays that are smaller than the specified buffer size, copies are made of all non-contiguous, mis-aligned, or out-of- @@ -441,7 +441,7 @@ execution possibilities. If :cdata:`NPY_ALLOW_THREADS` is defined during compilation, then the Python Global Interpreter Lock (GIL) is released prior to calling all of these loops (as long as they don't involve object arrays). It is re-acquired if necessary to handle error -conditions. The hardware error flags are checked only after the 1-d +conditions. The hardware error flags are checked only after the 1-D loop is calcluated. @@ -449,10 +449,10 @@ One Loop ^^^^^^^^ This is the simplest case of all. The ufunc is executed by calling the -underlying 1-d loop exactly once. This is possible only when we have +underlying 1-D loop exactly once. This is possible only when we have aligned data of the correct type (including byte-order) for both input and output and all arrays have uniform strides (either contiguous, -0-d, or 1-d). In this case, the 1-d computational loop is called once +0-D, or 1-D). In this case, the 1-D computational loop is called once to compute the calculation for the entire array. Note that the hardware error flags are only checked after the entire calculation is complete. @@ -462,13 +462,13 @@ Strided Loop ^^^^^^^^^^^^ When the input and output arrays are aligned and of the correct type, -but the striding is not uniform (non-contiguous and 2-d or larger), +but the striding is not uniform (non-contiguous and 2-D or larger), then a second looping structure is employed for the calculation. This approach converts all of the iterators for the input and output arguments to iterate over all but the largest dimension. The inner -loop is then handled by the underlying 1-d computational loop. The +loop is then handled by the underlying 1-D computational loop. The outer loop is a standard iterator loop on the converted iterators. The -hardware error flags are checked after each 1-d loop is completed. +hardware error flags are checked after each 1-D loop is completed. Buffered Loop @@ -476,12 +476,12 @@ Buffered Loop This is the code that handles the situation whenever the input and/or output arrays are either misaligned or of the wrong data-type -(including being byte-swapped) from what the underlying 1-d loop +(including being byte-swapped) from what the underlying 1-D loop expects. The arrays are also assumed to be non-contiguous. The code -works very much like the strided loop except for the inner 1-d loop is +works very much like the strided loop except for the inner 1-D loop is modified so that pre-processing is performed on the inputs and post- processing is performed on the outputs in bufsize chunks (where -bufsize is a user-settable parameter). The underlying 1-d +bufsize is a user-settable parameter). The underlying 1-D computational loop is called on data that is copied over (if it needs to be). The setup code and the loop code is considerably more complicated in this case because it has to handle: @@ -497,10 +497,10 @@ complicated in this case because it has to handle: - special-casing Object arrays so that reference counts are properly handled when copies and/or casts are necessary. -- breaking up the inner 1-d loop into bufsize chunks (with a possible +- breaking up the inner 1-D loop into bufsize chunks (with a possible remainder). -Again, the hardware error flags are checked at the end of each 1-d +Again, the hardware error flags are checked at the end of each 1-D loop. @@ -544,7 +544,7 @@ The setup function for all three methods is ``construct_reduce``. This function creates a reducing loop object and fills it with parameters needed to complete the loop. All of the methods only work on ufuncs that take 2-inputs and return 1 output. Therefore, the -underlying 1-d loop is selected assuming a signature of [ ``otype``, +underlying 1-D loop is selected assuming a signature of [ ``otype``, ``otype``, ``otype`` ] where ``otype`` is the requested reduction data-type. The buffer size and error handling is then retrieved from (per-thread) global storage. For small arrays that are mis-aligned or @@ -573,10 +573,10 @@ Reduce .. index:: triple: ufunc; methods; reduce -All of the ufunc methods use the same underlying 1-d computational +All of the ufunc methods use the same underlying 1-D computational loops with input and output arguments adjusted so that the appropriate reduction takes place. For example, the key to the functioning of -reduce is that the 1-d loop is called with the output and the second +reduce is that the 1-D loop is called with the output and the second input pointing to the same position in memory and both having a step- size of 0. The first input is pointing to the input array with a step- size given by the appropriate stride for the selected axis. In this @@ -594,7 +594,7 @@ where :math:`N+1` is the number of elements in the input, :math:`i`, :math:`o` is the output, and :math:`i[k]` is the :math:`k^{\textrm{th}}` element of :math:`i` along the selected axis. This basic operations is repeated for arrays with greater than 1 -dimension so that the reduction takes place for every 1-d sub-array +dimension so that the reduction takes place for every 1-D sub-array along the selected axis. An iterator with the selected dimension removed handles this looping. @@ -625,9 +625,10 @@ the current output pointer. Thus, the operation performed is o[k] & = & i[k]\textrm{<op>}o[k-1]\quad k=1\ldots N. \end{align*} -The output has the same shape as the input and each 1-d loop operates -over :math:`N` elements when the shape in the selected axis is :math:`N+1`. Again, buffered loops take care to copy and cast the data before -calling the underlying 1-d computational loop. +The output has the same shape as the input and each 1-D loop operates +over :math:`N` elements when the shape in the selected axis is :math:`N+1`. +Again, buffered loops take care to copy and cast the data before +calling the underlying 1-D computational loop. Reduceat @@ -645,21 +646,21 @@ the selected dimension before the loop calculations take place. The loop implementation is handled using code that is very similar to the reduce code repeated as many times as there are elements in the indices input. In particular: the first input pointer passed to the -underlying 1-d computational loop points to the input array at the +underlying 1-D computational loop points to the input array at the correct location indicated by the index array. In addition, the output -pointer and the second input pointer passed to the underlying 1-d loop -point to the same position in memory. The size of the 1-d +pointer and the second input pointer passed to the underlying 1-D loop +point to the same position in memory. The size of the 1-D computational loop is fixed to be the difference between the current index and the next index (when the current index is the last index, then the next index is assumed to be the length of the array along the -selected dimension). In this way, the 1-d loop will implement a reduce +selected dimension). In this way, the 1-D loop will implement a reduce over the specified indices. Mis-aligned or a loop data-type that does not match the input and/or output data-type is handled using buffered code where-in data is copied to a temporary buffer and cast to the correct data-type if -necessary prior to calling the underlying 1-d function. The temporary +necessary prior to calling the underlying 1-D function. The temporary buffers are created in (element) sizes no bigger than the user settable buffer-size value. Thus, the loop must be flexible enough to -call the underlying 1-d computational loop enough times to complete +call the underlying 1-D computational loop enough times to complete the total calculation in chunks no bigger than the buffer-size. diff --git a/doc/source/reference/maskedarray.generic.rst b/doc/source/reference/maskedarray.generic.rst index 7c998ae63..bb8695408 100644 --- a/doc/source/reference/maskedarray.generic.rst +++ b/doc/source/reference/maskedarray.generic.rst @@ -19,11 +19,19 @@ that supports data arrays with masks. What is a masked array? ----------------------- -In many circumstances, datasets can be incomplete or tainted by the presence of invalid data. For example, a sensor may have failed to record a data, or -recorded an invalid value. -The :mod:`numpy.ma` module provides a convenient way to address this issue, by introducing masked arrays. - -A masked array is the combination of a standard :class:`numpy.ndarray` and a mask. A mask is either :attr:`nomask`, indicating that no value of the associated array is invalid, or an array of booleans that determines for each element of the associated array whether the value is valid or not. When an element of the mask is ``False``, the corresponding element of the associated array is valid and is said to be unmasked. When an element of the mask is ``True``, the corresponding element of the associated array is said to be masked (invalid). +In many circumstances, datasets can be incomplete or tainted by the presence +of invalid data. For example, a sensor may have failed to record a data, or +recorded an invalid value. The :mod:`numpy.ma` module provides a convenient +way to address this issue, by introducing masked arrays. + +A masked array is the combination of a standard :class:`numpy.ndarray` and a +mask. A mask is either :attr:`nomask`, indicating that no value of the +associated array is invalid, or an array of booleans that determines for each +element of the associated array whether the value is valid or not. When an +element of the mask is ``False``, the corresponding element of the associated +array is valid and is said to be unmasked. When an element of the mask is +``True``, the corresponding element of the associated array is said to be +masked (invalid). The package ensures that masked entries are not used in computations. @@ -38,7 +46,8 @@ array:: >>> mx = ma.masked_array(x, mask=[0, 0, 0, 1, 0]) -We can now compute the mean of the dataset, without taking the invalid data into account:: +We can now compute the mean of the dataset, without taking the invalid data +into account:: >>> mx.mean() 2.75 @@ -48,8 +57,9 @@ The :mod:`numpy.ma` module -------------------------- -The main feature of the :mod:`numpy.ma` module is the :class:`MaskedArray` class, which is a subclass of :class:`numpy.ndarray`. -The class, its attributes and methods are described in more details in the +The main feature of the :mod:`numpy.ma` module is the :class:`MaskedArray` +class, which is a subclass of :class:`numpy.ndarray`. The class, its +attributes and methods are described in more details in the :ref:`MaskedArray class <maskedarray.baseclass>` section. The :mod:`numpy.ma` module can be used as an addition to :mod:`numpy`: :: @@ -138,30 +148,40 @@ Accessing the data The underlying data of a masked array can be accessed in several ways: -* through the :attr:`~MaskedArray.data` attribute. The output is a view of the array as - a :class:`numpy.ndarray` or one of its subclasses, depending on the type - of the underlying data at the masked array creation. +* through the :attr:`~MaskedArray.data` attribute. The output is a view of the + array as a :class:`numpy.ndarray` or one of its subclasses, depending on the + type of the underlying data at the masked array creation. -* through the :meth:`~MaskedArray.__array__` method. The output is then a :class:`numpy.ndarray`. +* through the :meth:`~MaskedArray.__array__` method. The output is then a + :class:`numpy.ndarray`. -* by directly taking a view of the masked array as a :class:`numpy.ndarray` or one of its subclass (which is actually what using the :attr:`~MaskedArray.data` attribute does). +* by directly taking a view of the masked array as a :class:`numpy.ndarray` + or one of its subclass (which is actually what using the + :attr:`~MaskedArray.data` attribute does). * by using the :func:`getdata` function. -None of these methods is completely satisfactory if some entries have been marked as invalid. As a general rule, where a representation of the array is required without any masked entries, it is recommended to fill the array with the :meth:`filled` method. +None of these methods is completely satisfactory if some entries have been +marked as invalid. As a general rule, where a representation of the array is +required without any masked entries, it is recommended to fill the array with +the :meth:`filled` method. Accessing the mask ------------------ -The mask of a masked array is accessible through its :attr:`~MaskedArray.mask` attribute. -We must keep in mind that a ``True`` entry in the mask indicates an *invalid* data. +The mask of a masked array is accessible through its :attr:`~MaskedArray.mask` +attribute. We must keep in mind that a ``True`` entry in the mask indicates an +*invalid* data. -Another possibility is to use the :func:`getmask` and :func:`getmaskarray` functions. :func:`getmask(x)` outputs the mask of ``x`` if ``x`` is a masked array, and the special value :data:`nomask` otherwise. -:func:`getmaskarray(x)` outputs the mask of ``x`` if ``x`` is a masked array. -If ``x`` has no invalid entry or is not a masked array, the function outputs a boolean array of ``False`` with as many elements as ``x``. +Another possibility is to use the :func:`getmask` and :func:`getmaskarray` +functions. :func:`getmask(x)` outputs the mask of ``x`` if ``x`` is a masked +array, and the special value :data:`nomask` otherwise. :func:`getmaskarray(x)` +outputs the mask of ``x`` if ``x`` is a masked array. If ``x`` has no invalid +entry or is not a masked array, the function outputs a boolean array of +``False`` with as many elements as ``x``. @@ -169,7 +189,9 @@ If ``x`` has no invalid entry or is not a masked array, the function outputs a Accessing only the valid entries --------------------------------- -To retrieve only the valid entries, we can use the inverse of the mask as an index. The inverse of the mask can be calculated with the :func:`numpy.logical_not` function or simply with the ``~`` operator:: +To retrieve only the valid entries, we can use the inverse of the mask as an +index. The inverse of the mask can be calculated with the +:func:`numpy.logical_not` function or simply with the ``~`` operator:: >>> x = ma.array([[1, 2], [3, 4]], mask=[[0, 1], [1, 0]]) >>> x[~x.mask] @@ -177,9 +199,10 @@ To retrieve only the valid entries, we can use the inverse of the mask as an ind mask = [False False], fill_value = 999999) -Another way to retrieve the valid data is to use the :meth:`compressed` method, -which returns a one-dimensional :class:`~numpy.ndarray` (or one of its subclasses, -depending on the value of the :attr:`~MaskedArray.baseclass` attribute):: +Another way to retrieve the valid data is to use the :meth:`compressed` +method, which returns a one-dimensional :class:`~numpy.ndarray` (or one of its +subclasses, depending on the value of the :attr:`~MaskedArray.baseclass` +attribute):: >>> x.compressed() array([1, 4]) @@ -194,7 +217,8 @@ Modifying the mask Masking an entry ~~~~~~~~~~~~~~~~ -The recommended way to mark one or several specific entries of a masked array as invalid is to assign the special value :attr:`masked` to them:: +The recommended way to mark one or several specific entries of a masked array +as invalid is to assign the special value :attr:`masked` to them:: >>> x = ma.array([1, 2, 3]) >>> x[0] = ma.masked @@ -226,10 +250,15 @@ A second possibility is to modify the :attr:`~MaskedArray.mask` directly, but this usage is discouraged. .. note:: - When creating a new masked array with a simple, non-structured datatype, the mask is initially set to the special value :attr:`nomask`, that corresponds roughly to the boolean ``False``. Trying to set an element of :attr:`nomask` will fail with a :exc:`TypeError` exception, as a boolean does not support item assignment. + When creating a new masked array with a simple, non-structured datatype, + the mask is initially set to the special value :attr:`nomask`, that + corresponds roughly to the boolean ``False``. Trying to set an element of + :attr:`nomask` will fail with a :exc:`TypeError` exception, as a boolean + does not support item assignment. -All the entries of an array can be masked at once by assigning ``True`` to the mask:: +All the entries of an array can be masked at once by assigning ``True`` to the +mask:: >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) >>> x.mask = True @@ -238,7 +267,8 @@ All the entries of an array can be masked at once by assigning ``True`` to the m mask = [ True True True], fill_value = 999999) -Finally, specific entries can be masked and/or unmasked by assigning to the mask a sequence of booleans:: +Finally, specific entries can be masked and/or unmasked by assigning to the +mask a sequence of booleans:: >>> x = ma.array([1, 2, 3]) >>> x.mask = [0, 1, 0] @@ -250,7 +280,8 @@ Finally, specific entries can be masked and/or unmasked by assigning to the mask Unmasking an entry ~~~~~~~~~~~~~~~~~~ -To unmask one or several specific entries, we can just assign one or several new valid values to them:: +To unmask one or several specific entries, we can just assign one or several +new valid values to them:: >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) >>> x @@ -264,12 +295,12 @@ To unmask one or several specific entries, we can just assign one or several new fill_value = 999999) .. note:: - Unmasking an entry by direct assignment will silently fail if the masked array - has a *hard* mask, as shown by the :attr:`hardmask` attribute. - This feature was introduced to prevent overwriting the mask. - To force the unmasking of an entry where the array has a hard mask, the mask must first - to be softened using the :meth:`soften_mask` method before the allocation. It can be re-hardened - with :meth:`harden_mask`:: + Unmasking an entry by direct assignment will silently fail if the masked + array has a *hard* mask, as shown by the :attr:`hardmask` attribute. This + feature was introduced to prevent overwriting the mask. To force the + unmasking of an entry where the array has a hard mask, the mask must first + to be softened using the :meth:`soften_mask` method before the allocation. + It can be re-hardened with :meth:`harden_mask`:: >>> x = ma.array([1, 2, 3], mask=[0, 0, 1], hard_mask=True) >>> x @@ -290,7 +321,9 @@ To unmask one or several specific entries, we can just assign one or several new >>> x.harden_mask() -To unmask all masked entries of a masked array (provided the mask isn't a hard mask), the simplest solution is to assign the constant :attr:`nomask` to the mask:: +To unmask all masked entries of a masked array (provided the mask isn't a hard +mask), the simplest solution is to assign the constant :attr:`nomask` to the +mask:: >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) >>> x @@ -308,9 +341,13 @@ To unmask all masked entries of a masked array (provided the mask isn't a hard m Indexing and slicing -------------------- -As a :class:`MaskedArray` is a subclass of :class:`numpy.ndarray`, it inherits its mechanisms for indexing and slicing. +As a :class:`MaskedArray` is a subclass of :class:`numpy.ndarray`, it inherits +its mechanisms for indexing and slicing. -When accessing a single entry of a masked array with no named fields, the output is either a scalar (if the corresponding entry of the mask is ``False``) or the special value :attr:`masked` (if the corresponding entry of the mask is ``True``):: +When accessing a single entry of a masked array with no named fields, the +output is either a scalar (if the corresponding entry of the mask is +``False``) or the special value :attr:`masked` (if the corresponding entry of +the mask is ``True``):: >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) >>> x[0] @@ -323,7 +360,9 @@ When accessing a single entry of a masked array with no named fields, the output True If the masked array has named fields, accessing a single entry returns a -:class:`numpy.void` object if none of the fields are masked, or a 0d masked array with the same dtype as the initial array if at least one of the fields is masked. +:class:`numpy.void` object if none of the fields are masked, or a 0d masked +array with the same dtype as the initial array if at least one of the fields +is masked. >>> y = ma.masked_array([(1,2), (3, 4)], ... mask=[(0, 0), (0, 1)], @@ -337,7 +376,11 @@ If the masked array has named fields, accessing a single entry returns a dtype = [('a', '<i4'), ('b', '<i4')]) -When accessing a slice, the output is a masked array whose :attr:`~MaskedArray.data` attribute is a view of the original data, and whose mask is either :attr:`nomask` (if there was no invalid entries in the original array) or a copy of the corresponding slice of the original mask. The copy is required to avoid propagation of any modification of the mask to the original. +When accessing a slice, the output is a masked array whose +:attr:`~MaskedArray.data` attribute is a view of the original data, and whose +mask is either :attr:`nomask` (if there was no invalid entries in the original +array) or a copy of the corresponding slice of the original mask. The copy is +required to avoid propagation of any modification of the mask to the original. >>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1]) >>> mx = x[:3] @@ -356,31 +399,39 @@ When accessing a slice, the output is a masked array whose :attr:`~MaskedArray.d array([ 1, -1, 3, 4, 5]) -Accessing a field of a masked array with structured datatype returns a :class:`MaskedArray`. - - +Accessing a field of a masked array with structured datatype returns a +:class:`MaskedArray`. Operations on masked arrays --------------------------- Arithmetic and comparison operations are supported by masked arrays. -As much as possible, invalid entries of a masked array are not processed, meaning that the -corresponding :attr:`data` entries *should* be the same before and after the operation. +As much as possible, invalid entries of a masked array are not processed, +meaning that the corresponding :attr:`data` entries *should* be the same +before and after the operation. .. warning:: - We need to stress that this behavior may not be systematic, that masked data may be affected - by the operation in some cases and therefore users should not rely on this data remaining unchanged. + We need to stress that this behavior may not be systematic, that masked + data may be affected by the operation in some cases and therefore users + should not rely on this data remaining unchanged. The :mod:`numpy.ma` module comes with a specific implementation of most -ufuncs. -Unary and binary functions that have a validity domain (such as :func:`~numpy.log` or :func:`~numpy.divide`) return the :data:`masked` constant whenever the input is masked or falls outside the validity domain:: +ufuncs. Unary and binary functions that have a validity domain (such as +:func:`~numpy.log` or :func:`~numpy.divide`) return the :data:`masked` +constant whenever the input is masked or falls outside the validity domain:: >>> ma.log([-1, 0, 1, 2]) masked_array(data = [-- -- 0.0 0.69314718056], mask = [ True True False False], fill_value = 1e+20) -Masked arrays also support standard numpy ufuncs. The output is then a masked array. The result of a unary ufunc is masked wherever the input is masked. The result of a binary ufunc is masked wherever any of the input is masked. If the ufunc also returns the optional context output (a 3-element tuple containing the name of the ufunc, its arguments and its domain), the context is processed and entries of the output masked array are masked wherever the corresponding input fall outside the validity domain:: +Masked arrays also support standard numpy ufuncs. The output is then a masked +array. The result of a unary ufunc is masked wherever the input is masked. The +result of a binary ufunc is masked wherever any of the input is masked. If the +ufunc also returns the optional context output (a 3-element tuple containing +the name of the ufunc, its arguments and its domain), the context is processed +and entries of the output masked array are masked wherever the corresponding +input fall outside the validity domain:: >>> x = ma.array([-1, 1, 0, 2, 3], mask=[0, 0, 0, 0, 1]) >>> np.log(x) @@ -396,8 +447,9 @@ Examples Data with a given value representing missing data ------------------------------------------------- -Let's consider a list of elements, ``x``, where values of -9999. represent missing data. -We wish to compute the average value of the data and the vector of anomalies (deviations from the average):: +Let's consider a list of elements, ``x``, where values of -9999. represent +missing data. We wish to compute the average value of the data and the vector +of anomalies (deviations from the average):: >>> import numpy.ma as ma >>> x = [0.,1.,-9999.,3.,4.] @@ -423,7 +475,8 @@ replaced by the average value. Numerical operations -------------------- -Numerical operations can be easily performed without worrying about missing values, dividing by zero, square roots of negative numbers, etc.:: +Numerical operations can be easily performed without worrying about missing +values, dividing by zero, square roots of negative numbers, etc.:: >>> import numpy as np, numpy.ma as ma >>> x = ma.array([1., -1., 3., 4., 5., 6.], mask=[0,0,0,0,1,0]) @@ -431,13 +484,16 @@ Numerical operations can be easily performed without worrying about missing valu >>> print np.sqrt(x/y) [1.0 -- -- 1.0 -- --] -Four values of the output are invalid: the first one comes from taking the square root of a negative number, the second from the division by zero, and the last two where the inputs were masked. +Four values of the output are invalid: the first one comes from taking the +square root of a negative number, the second from the division by zero, and +the last two where the inputs were masked. Ignoring extreme values ----------------------- -Let's consider an array ``d`` of random floats between 0 and 1. -We wish to compute the average of the values of ``d`` while ignoring any data outside the range ``[0.1, 0.9]``:: +Let's consider an array ``d`` of random floats between 0 and 1. We wish to +compute the average of the values of ``d`` while ignoring any data outside +the range ``[0.1, 0.9]``:: >>> print ma.masked_outside(d, 0.1, 0.9).mean() diff --git a/doc/source/reference/routines.array-creation.rst b/doc/source/reference/routines.array-creation.rst index ef9c0041d..23b35243b 100644 --- a/doc/source/reference/routines.array-creation.rst +++ b/doc/source/reference/routines.array-creation.rst @@ -44,7 +44,8 @@ From existing data Creating record arrays (:mod:`numpy.rec`) ----------------------------------------- -.. note:: :mod:`numpy.rec` is the preferred alias for :mod:`numpy.core.records`. +.. note:: :mod:`numpy.rec` is the preferred alias for + :mod:`numpy.core.records`. .. autosummary:: :toctree: generated/ @@ -60,7 +61,8 @@ Creating record arrays (:mod:`numpy.rec`) Creating character arrays (:mod:`numpy.char`) --------------------------------------------- -.. note:: :mod:`numpy.char` is the preferred alias for :mod:`numpy.core.defchararray`. +.. note:: :mod:`numpy.char` is the preferred alias for + :mod:`numpy.core.defchararray`. .. autosummary:: :toctree: generated/ diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst index 90fe1c189..0788d3a0a 100644 --- a/doc/source/reference/routines.rst +++ b/doc/source/reference/routines.rst @@ -2,6 +2,16 @@ Routines ******** +In this chapter routine docstrings are presented, grouped by functionality. +Many docstrings contain example code, which demonstrates basic usage +of the routine. The examples assume that NumPy is imported with:: + + >>> import numpy as np + +A convenient way to execute examples is the ``%doctest_mode`` mode of +IPython, which allows for pasting of multi-line examples and preserves +indentation. + .. toctree:: :maxdepth: 2 diff --git a/doc/source/user/basics.indexing.rst b/doc/source/user/basics.indexing.rst index f218fd060..8844adcae 100644 --- a/doc/source/user/basics.indexing.rst +++ b/doc/source/user/basics.indexing.rst @@ -6,11 +6,4 @@ Indexing .. seealso:: :ref:`Indexing routines <routines.indexing>` -.. note:: - - XXX: Combine ``numpy.doc.indexing`` with material - section 2.2 Basic indexing? - Or incorporate the material directly here? - - .. automodule:: numpy.doc.indexing diff --git a/doc/source/user/basics.rec.rst b/doc/source/user/basics.rec.rst index 81a3de8e3..ce6c3b851 100644 --- a/doc/source/user/basics.rec.rst +++ b/doc/source/user/basics.rec.rst @@ -1,3 +1,5 @@ +.. _structured_arrays: + *************************************** Structured arrays (aka "Record arrays") *************************************** diff --git a/doc/source/user/basics.rst b/doc/source/user/basics.rst index 85e79c25d..bbc3ab174 100644 --- a/doc/source/user/basics.rst +++ b/doc/source/user/basics.rst @@ -2,11 +2,6 @@ Numpy basics ************ -.. note:: - - XXX: there is overlap between this text extracted from ``numpy.doc`` - and "Guide to Numpy" chapter 2. Needs combining? - .. toctree:: :maxdepth: 2 diff --git a/doc/source/user/basics.types.rst b/doc/source/user/basics.types.rst index 4982045a2..5ce5af15a 100644 --- a/doc/source/user/basics.types.rst +++ b/doc/source/user/basics.types.rst @@ -4,11 +4,4 @@ Data types .. seealso:: :ref:`Data type objects <arrays.dtypes>` -.. note:: - - XXX: Combine ``numpy.doc.indexing`` with material from - "Guide to Numpy" (section 2.1 Data-Type descriptors)? - Or incorporate the material directly here? - - .. automodule:: numpy.doc.basics diff --git a/doc/source/user/c-info.beyond-basics.rst b/doc/source/user/c-info.beyond-basics.rst index 703124b58..563467e72 100644 --- a/doc/source/user/c-info.beyond-basics.rst +++ b/doc/source/user/c-info.beyond-basics.rst @@ -159,17 +159,18 @@ Broadcasting over multiple arrays .. index:: single: broadcasting -When multiple arrays are involved in an operation, you may want to use the same -broadcasting rules that the math operations ( *i.e.* the ufuncs) use. This can -be done easily using the :ctype:`PyArrayMultiIterObject`. This is the object -returned from the Python command numpy.broadcast and it is almost as easy to -use from C. The function :cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is -used (with ``n`` input objects in place of ``...`` ). The input objects can be -arrays or anything that can be converted into an array. A pointer to a -PyArrayMultiIterObject is returned. Broadcasting has already been accomplished -which adjusts the iterators so that all that needs to be done to advance to the -next element in each array is for PyArray_ITER_NEXT to be called for each of -the inputs. This incrementing is automatically performed by +When multiple arrays are involved in an operation, you may want to use the +same broadcasting rules that the math operations (*i.e.* the ufuncs) use. +This can be done easily using the :ctype:`PyArrayMultiIterObject`. This is +the object returned from the Python command numpy.broadcast and it is almost +as easy to use from C. The function +:cfunc:`PyArray_MultiIterNew` ( ``n``, ``...`` ) is used (with ``n`` input +objects in place of ``...`` ). The input objects can be arrays or anything +that can be converted into an array. A pointer to a PyArrayMultiIterObject is +returned. Broadcasting has already been accomplished which adjusts the +iterators so that all that needs to be done to advance to the next element in +each array is for PyArray_ITER_NEXT to be called for each of the inputs. This +incrementing is automatically performed by :cfunc:`PyArray_MultiIter_NEXT` ( ``obj`` ) macro (which can handle a multiterator ``obj`` as either a :ctype:`PyArrayMultiObject *` or a :ctype:`PyObject *`). The data from input number ``i`` is available using @@ -233,15 +234,19 @@ can be used. The function call used to create a new ufunc to work on built-in data-types is given below. A different mechanism is used to register ufuncs for user-defined data-types. -.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, void** data, char* types, int ntypes, int nin, int nout, int identity, char* name, char* doc, int check_return) +.. cfunction:: PyObject *PyUFunc_FromFuncAndData( PyUFuncGenericFunction* func, + void** data, char* types, int ntypes, int nin, int nout, int identity, + char* name, char* doc, int check_return) *func* A pointer to an array of 1-d functions to use. This array must be at - least ntypes long. Each entry in the array must be a ``PyUFuncGenericFunction`` function. This function has the following signature. An example of a - valid 1d loop function is also given. + least ntypes long. Each entry in the array must be a + ``PyUFuncGenericFunction`` function. This function has the following + signature. An example of a valid 1d loop function is also given. - .. cfunction:: void loop1d(char** args, npy_intp* dimensions, npy_intp* steps, void* data) + .. cfunction:: void loop1d(char** args, npy_intp* dimensions, + npy_intp* steps, void* data) *args* @@ -269,7 +274,8 @@ register ufuncs for user-defined data-types. .. code-block:: c static void - double_add(char *args, npy_intp *dimensions, npy_intp *steps, void *extra) + double_add(char *args, npy_intp *dimensions, npy_intp *steps, + void *extra) { npy_intp i; npy_intp is1=steps[0], is2=steps[1]; @@ -320,9 +326,9 @@ register ufuncs for user-defined data-types. *identity* - Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, :cdata:`PyUFunc_None`. - This specifies what should be returned when an empty array is - passed to the reduce method of the ufunc. + Either :cdata:`PyUFunc_One`, :cdata:`PyUFunc_Zero`, + :cdata:`PyUFunc_None`. This specifies what should be returned when + an empty array is passed to the reduce method of the ufunc. *name* @@ -458,7 +464,8 @@ functions for each conversion you want to support and then registering these functions with the data-type descriptor. A low-level casting function has the signature. -.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr, void* toarr) +.. cfunction:: void castfunc( void* from, void* to, npy_intp n, void* fromarr, + void* toarr) Cast ``n`` elements ``from`` one type ``to`` another. The data to cast from is in a contiguous, correctly-swapped and aligned chunk @@ -531,7 +538,8 @@ previously created. Then you call :cfunc:`PyUFunc_RegisterLoopForType` this function is ``0`` if the process was successful and ``-1`` with an error condition set if it was not successful. -.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc, int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) +.. cfunction:: int PyUFunc_RegisterLoopForType( PyUFuncObject* ufunc, + int usertype, PyUFuncGenericFunction function, int* arg_types, void* data) *ufunc* @@ -661,10 +669,6 @@ Specific features of ndarray sub-typing Some special methods and attributes are used by arrays in order to facilitate the interoperation of sub-types with the base ndarray type. -.. note:: XXX: some of the documentation below needs to be moved to the - reference guide. - - The __array_finalize\__ method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/user/c-info.python-as-glue.rst b/doc/source/user/c-info.python-as-glue.rst index 4fb337821..6ce266859 100644 --- a/doc/source/user/c-info.python-as-glue.rst +++ b/doc/source/user/c-info.python-as-glue.rst @@ -13,7 +13,7 @@ Using Python as glue Many people like to say that Python is a fantastic glue language. Hopefully, this Chapter will convince you that this is true. The first adopters of Python for science were typically people who used it to -glue together large applicaton codes running on super-computers. Not +glue together large application codes running on super-computers. Not only was it much nicer to code in Python than in a shell script or Perl, in addition, the ability to easily extend Python made it relatively easy to create new classes and types specifically adapted @@ -123,8 +123,7 @@ F2py allows you to automatically construct an extension module that interfaces to routines in Fortran 77/90/95 code. It has the ability to parse Fortran 77/90/95 code and automatically generate Python signatures for the subroutines it encounters, or you can guide how the -subroutine interfaces with Python by constructing an interface- -defintion-file (or modifying the f2py-produced one). +subroutine interfaces with Python by constructing an interface-definition-file (or modifying the f2py-produced one). .. index:: single: f2py @@ -175,7 +174,7 @@ be imported from Python:: This command leaves a file named add.{ext} in the current directory (where {ext} is the appropriate extension for a python extension module on your platform --- so, pyd, *etc.* ). This module may then be -imported from Python. It will contain a method for each subroutin in +imported from Python. It will contain a method for each subroutine in add (zadd, cadd, dadd, sadd). The docstring of each method contains information about how the module method may be called: @@ -586,7 +585,7 @@ produce a robust but fast subroutine. One final note about weave.inline: if you have additional code you want to include in the final extension module such as supporting -function calls, include statments, etc. you can pass this code in as a +function calls, include statements, etc. you can pass this code in as a string using the keyword support_code: ``weave.inline(code, variables, support_code=support)``. If you need the extension module to link against an additional library then you can also pass in @@ -784,7 +783,7 @@ details. Pyrex-filter ------------ -The two-dimensional example we created using weave is a bit uglierto +The two-dimensional example we created using weave is a bit uglier to implement in Pyrex because two-dimensional indexing using Pyrex is not as simple. But, it is straightforward (and possibly faster because of pre-computed indices). Here is the Pyrex-file I named image.pyx. @@ -873,7 +872,7 @@ There are several disadvantages of using Pyrex: 4. Multi-dimensional arrays are "bulky" to index (appropriate macros may be able to fix this). -5. The C-code generated by Prex is hard to read and modify (and typically +5. The C-code generated by Pyrex is hard to read and modify (and typically compiles with annoying but harmless warnings). Writing a good Pyrex extension module still takes a bit of effort @@ -1126,8 +1125,8 @@ significantly safer to call a C-function using ctypes and the data- area of an ndarray. You may still want to wrap the function in an additional Python wrapper to make it user-friendly (hiding some obvious arguments and making some arguments output arguments). In this -process, the **requires** function in NumPy may be useful to return the right kind of array from -a given input. +process, the **requires** function in NumPy may be useful to return the right +kind of array from a given input. Complete example diff --git a/doc/source/user/howtofind.rst b/doc/source/user/howtofind.rst index 5f6b49012..00ed5daa7 100644 --- a/doc/source/user/howtofind.rst +++ b/doc/source/user/howtofind.rst @@ -4,6 +4,4 @@ How to find documentation .. seealso:: :ref:`Numpy-specific help functions <routines.help>` -.. note:: XXX: this part is not yet written. - .. automodule:: numpy.doc.howtofind diff --git a/doc/source/user/install.rst b/doc/source/user/install.rst index 1941ebb29..06b2115da 100644 --- a/doc/source/user/install.rst +++ b/doc/source/user/install.rst @@ -12,29 +12,30 @@ Windows ------- Good solutions for Windows are, The Enthought Python Distribution `(EPD) -<http://www.enthought.com/products/epd.php>`_ (which provides binary installers -for Windows, OS X and Redhat) and `Python (x, y) <http://www.pythonxy.com>`_. -Both of these packages include Python, NumPy and many additional packages. -A lightweight alternative is to download the Python installer from -`www.python.org <http://www.python.org>`_ and the NumPy installer for your -Python version from the Sourceforge `download site -<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_ +<http://www.enthought.com/products/epd.php>`_ (which provides binary +installers for Windows, OS X and Redhat) and `Python (x, y) +<http://www.pythonxy.com>`_. Both of these packages include Python, NumPy and +many additional packages. A lightweight alternative is to download the Python +installer from `www.python.org <http://www.python.org>`_ and the NumPy +installer for your Python version from the Sourceforge `download site <http:// +sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_ Linux ----- Most of the major distributions provide packages for NumPy, but these can lag behind the most recent NumPy release. Pre-built binary packages for Ubuntu are -available on the `scipy ppa <https://edge.launchpad.net/~scipy/+archive/ppa>`_. -Redhat binaries are available in the `EPD -<http://www.enthought.com/products/epd.php>`_. +available on the `scipy ppa +<https://edge.launchpad.net/~scipy/+archive/ppa>`_. Redhat binaries are +available in the `EPD <http://www.enthought.com/products/epd.php>`_. Mac OS X -------- A universal binary installer for NumPy is available from the `download site -<http://sourceforge.net/project/showfiles.php?group_id=1369&package_id=175103>`_. -The `EPD <http://www.enthought.com/products/epd.php>`_ provides NumPy binaries. +<http://sourceforge.net/project/showfiles.php?group_id=1369& +package_id=175103>`_. The `EPD <http://www.enthought.com/products/epd.php>`_ +provides NumPy binaries. Building from source ==================== @@ -62,21 +63,22 @@ Building NumPy requires the following software installed: 2) Compilers - To build any extension modules for Python, you'll need a C compiler. Various - NumPy modules use FORTRAN 77 libraries, so you'll also need a FORTRAN 77 - compiler installed. + To build any extension modules for Python, you'll need a C compiler. + Various NumPy modules use FORTRAN 77 libraries, so you'll also need a + FORTRAN 77 compiler installed. - Note that NumPy is developed mainly using GNU compilers. Compilers from other - vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, Lahey, HP, - IBM, Microsoft are only supported in the form of community feedback, and may - not work out of the box. GCC 3.x (and later) compilers are recommended. + Note that NumPy is developed mainly using GNU compilers. Compilers from + other vendors such as Intel, Absoft, Sun, NAG, Compaq, Vast, Porland, + Lahey, HP, IBM, Microsoft are only supported in the form of community + feedback, and may not work out of the box. GCC 3.x (and later) compilers + are recommended. 3) Linear Algebra libraries - NumPy does not require any external linear algebra libraries to be installed. - However, if these are available, NumPy's setup script can detect them and use - them for building. A number of different LAPACK library setups can be used, - including optimized LAPACK libraries such as ATLAS, MKL or the + NumPy does not require any external linear algebra libraries to be + installed. However, if these are available, NumPy's setup script can detect + them and use them for building. A number of different LAPACK library setups + can be used, including optimized LAPACK libraries such as ATLAS, MKL or the Accelerate/vecLib framework on OS X. FORTRAN ABI mismatch @@ -87,8 +89,8 @@ Unfortunately, they are not ABI compatible, which means that concretely you should avoid mixing libraries built with one with another. In particular, if your blas/lapack/atlas is built with g77, you *must* use g77 when building numpy and scipy; on the contrary, if your atlas is built with gfortran, you -*must* build numpy/scipy with gfortran. This applies for most other cases where -different FORTRAN compilers might have been used. +*must* build numpy/scipy with gfortran. This applies for most other cases +where different FORTRAN compilers might have been used. Choosing the fortran compiler ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -110,9 +112,9 @@ How to check the ABI of blas/lapack/atlas One relatively simple and reliable way to check for the compiler used to build a library is to use ldd on the library. If libg2c.so is a dependency, this -means that g77 has been used. If libgfortran.so is a a dependency, gfortran has -been used. If both are dependencies, this means both have been used, which is -almost always a very bad idea. +means that g77 has been used. If libgfortran.so is a a dependency, gfortran +has been used. If both are dependencies, this means both have been used, which +is almost always a very bad idea. Building with ATLAS support --------------------------- diff --git a/doc/source/user/misc.rst b/doc/source/user/misc.rst index 4e2ec9fdb..0e1807f3f 100644 --- a/doc/source/user/misc.rst +++ b/doc/source/user/misc.rst @@ -2,8 +2,6 @@ Miscellaneous ************* -.. note:: XXX: This section is not yet written. - .. automodule:: numpy.doc.misc .. automodule:: numpy.doc.methods_vs_functions diff --git a/doc/source/user/performance.rst b/doc/source/user/performance.rst index 1f6e4e16c..59f8a2edc 100644 --- a/doc/source/user/performance.rst +++ b/doc/source/user/performance.rst @@ -2,6 +2,4 @@ Performance *********** -.. note:: XXX: This section is not yet written. - .. automodule:: numpy.doc.performance diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index bbb93f6f2..b6c5853e0 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -3985,6 +3985,12 @@ add_newdoc('numpy.core', 'ufunc', """ Functions that operate element by element on whole arrays. + To see the documentation for a specific ufunc, use np.info(). For + example, np.info(np.sin). Because ufuncs are written in C + (for speed) and linked into Python with NumPy's ufunc facility, + Python's help() function finds this page whenever help() is called + on a ufunc. + A detailed explanation of ufuncs can be found in the "ufuncs.rst" file in the NumPy reference guide. diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index 4adbf2376..c63df7c8f 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -1641,7 +1641,7 @@ add_newdoc('numpy.core.umath', 'left_shift', x1 : array_like of integer type Input values. x2 : array_like of integer type - Number of zeros to append to `x1`. + Number of zeros to append to `x1`. Has to be non-negative. Returns ------- @@ -1849,6 +1849,16 @@ add_newdoc('numpy.core.umath', 'log2', handles the floating-point negative zero as an infinitesimal negative number, conforming to the C99 standard. + Examples + -------- + >>> x = np.array([0, 1, 2, 2**4]) + >>> np.log2(x) + array([-Inf, 0., 1., 4.]) + + >>> xi = np.array([0+1.j, 1, 2+0.j, 4.j]) + >>> np.log2(xi) + array([ 0.+2.26618007j, 0.+0.j , 1.+0.j , 2.+2.26618007j]) + """) add_newdoc('numpy.core.umath', 'logaddexp', diff --git a/numpy/doc/constants.py b/numpy/doc/constants.py index adb7c7e02..722147dd8 100644 --- a/numpy/doc/constants.py +++ b/numpy/doc/constants.py @@ -75,8 +75,8 @@ add_newdoc('numpy', 'NINF', isnan : Shows which elements are Not a Number - isfinite : Shows which elements are finite (not one of - Not a Number, positive infinity and negative infinity) + isfinite : Shows which elements are finite (not one of Not a Number, + positive infinity and negative infinity) Notes ----- @@ -214,7 +214,7 @@ add_newdoc('numpy', 'e', """ Euler's constant, base of natural logarithms, Napier's constant. - `e = 2.71828182845904523536028747135266249775724709369995...` + ``e = 2.71828182845904523536028747135266249775724709369995...`` See Also -------- @@ -246,8 +246,8 @@ add_newdoc('numpy', 'inf', isnan : Shows which elements are Not a Number - isfinite : Shows which elements are finite (not one of - Not a Number, positive infinity and negative infinity) + isfinite : Shows which elements are finite (not one of Not a Number, + positive infinity and negative infinity) Notes ----- @@ -322,20 +322,20 @@ add_newdoc('numpy', 'newaxis', Examples -------- - >>> np.newaxis is None + >>> newaxis is None True >>> x = np.arange(3) >>> x array([0, 1, 2]) - >>> x[:, np.newaxis] + >>> x[:, newaxis] array([[0], [1], [2]]) - >>> x[:, np.newaxis, np.newaxis] + >>> x[:, newaxis, newaxis] array([[[0]], [[1]], [[2]]]) - >>> x[:, np.newaxis] * x + >>> x[:, newaxis] * x array([[0, 0, 0], [0, 1, 2], [0, 2, 4]]) @@ -343,20 +343,20 @@ add_newdoc('numpy', 'newaxis', Outer product, same as ``outer(x, y)``: >>> y = np.arange(3, 6) - >>> x[:, np.newaxis] * y + >>> x[:, newaxis] * y array([[ 0, 0, 0], [ 3, 4, 5], [ 6, 8, 10]]) ``x[newaxis, :]`` is equivalent to ``x[newaxis]`` and ``x[None]``: - >>> x[np.newaxis, :].shape + >>> x[newaxis, :].shape (1, 3) - >>> x[np.newaxis].shape + >>> x[newaxis].shape (1, 3) >>> x[None].shape (1, 3) - >>> x[:, np.newaxis].shape + >>> x[:, newaxis].shape (3, 1) """) |