diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/arrays.classes.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/arrays.interface.rst | 125 | ||||
| -rw-r--r-- | doc/source/reference/maskedarray.generic.rst | 38 | ||||
| -rw-r--r-- | doc/source/reference/routines.array-creation.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/routines.array-manipulation.rst | 6 | ||||
| -rw-r--r-- | doc/source/reference/routines.fft.rst | 59 | ||||
| -rw-r--r-- | doc/source/reference/routines.rst | 1 | ||||
| -rw-r--r-- | doc/source/reference/ufuncs.rst | 6 |
8 files changed, 150 insertions, 92 deletions
diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 865838699..671c95bbf 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -13,7 +13,7 @@ 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 can be replaced as a single array or does it +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 @@ -24,7 +24,7 @@ principal a subclass could redefine any aspect of the array and therefore, under strict guidelines, :func:`asanyarray` would rarely be useful. However, most subclasses of the arrayobject will not redefine certain aspects of the array object such as the buffer -interface, or the attributes of the array. One of important example, +interface, or the attributes of the array. One important example, however, of why your subroutine may not be able to handle an arbitrary subclass of an array is that matrices redefine the "*" operator to be matrix-multiplication, rather than element-by-element multiplication. @@ -77,7 +77,7 @@ Matrix objects :class:`matrix` objects inherit from the ndarray and therefore, they have the same attributes and methods of ndarrays. There are six -important differences of matrix objects, however that may lead to +important differences of matrix objects, however, that may lead to unexpected results when you use matrices but expect them to act like arrays: diff --git a/doc/source/reference/arrays.interface.rst b/doc/source/reference/arrays.interface.rst index 4afa3afc1..405e6da0a 100644 --- a/doc/source/reference/arrays.interface.rst +++ b/doc/source/reference/arrays.interface.rst @@ -11,16 +11,19 @@ The Array Interface .. warning:: This page describes the old, deprecated array interface. Everything still - works as described as of numpy 1.2 and on into the foreseeable future), but + works as described as of numpy 1.2 and on into the foreseeable future, but new development should target :pep:`3118` -- :cfunc:`The Revised Buffer Protocol <PyObject_GetBuffer>`. :pep:`3118` was incorporated into Python 2.6 and 3.0, and is additionally - supported by Cython's numpy buffer support. (See the Cython numpy - tutorial.) Cython provides a way to write code that supports the buffer + supported by Cython__'s numpy buffer support. (See the `Cython numpy + tutorial`__.) Cython provides a way to write code that supports the buffer protocol with Python versions older than 2.6 because it has a backward-compatible implementation utilizing the legacy array interface described here. +__ http://cython.org/ +__ http://wiki.cython.org/tutorials/numpy + :version: 3 The array interface (sometimes called array protocol) was created in @@ -206,6 +209,33 @@ array using only one attribute lookup and a well-defined C-structure. must also not reallocate their memory if other objects are referencing them. +The PyArrayInterface structure is defined in ``numpy/ndarrayobject.h`` +as:: + + typedef struct { + int two; /* contains the integer 2 -- simple sanity check */ + int nd; /* number of dimensions */ + char typekind; /* kind in array --- character code of typestr */ + int itemsize; /* size of each element */ + int flags; /* flags indicating how the data should be interpreted */ + /* must set ARR_HAS_DESCR bit to validate descr */ + Py_intptr_t *shape; /* A length-nd array of shape information */ + Py_intptr_t *strides; /* A length-nd array of stride information */ + void *data; /* A pointer to the first element of the array */ + PyObject *descr; /* NULL or data-description (same as descr key + of __array_interface__) -- must set ARR_HAS_DESCR + flag or this will be ignored. */ + } PyArrayInterface; + +The flags member may consist of 5 bits showing how the data should be +interpreted and one bit showing how the Interface should be +interpreted. The data-bits are :const:`CONTIGUOUS` (0x1), +:const:`FORTRAN` (0x2), :const:`ALIGNED` (0x100), :const:`NOTSWAPPED` +(0x200), and :const:`WRITEABLE` (0x400). A final flag +:const:`ARR_HAS_DESCR` (0x800) indicates whether or not this structure +has the arrdescr field. The field should not be accessed unless this +flag is present. + .. admonition:: New since June 16, 2006: In the past most implementations used the "desc" member of the @@ -215,3 +245,92 @@ array using only one attribute lookup and a well-defined C-structure. This is now an explicit part of the interface. Be sure to own a reference to the object when the :ctype:`PyCObject` is created using :ctype:`PyCObject_FromVoidPtrAndDesc`. + + +Type description examples +========================= + +For clarity it is useful to provide some examples of the type +description and corresponding :data:`__array_interface__` 'descr' +entries. Thanks to Scott Gilbert for these examples: + +In every case, the 'descr' key is optional, but of course provides +more information which may be important for various applications:: + + * Float data + typestr == '>f4' + descr == [('','>f4')] + + * Complex double + typestr == '>c8' + descr == [('real','>f4'), ('imag','>f4')] + + * RGB Pixel data + typestr == '|V3' + descr == [('r','|u1'), ('g','|u1'), ('b','|u1')] + + * Mixed endian (weird but could happen). + typestr == '|V8' (or '>u8') + descr == [('big','>i4'), ('little','<i4')] + + * Nested structure + struct { + int ival; + struct { + unsigned short sval; + unsigned char bval; + unsigned char cval; + } sub; + } + typestr == '|V8' (or '<u8' if you want) + descr == [('ival','<i4'), ('sub', [('sval','<u2'), ('bval','|u1'), ('cval','|u1') ]) ] + + * Nested array + struct { + int ival; + double data[16*4]; + } + typestr == '|V516' + descr == [('ival','>i4'), ('data','>f8',(16,4))] + + * Padded structure + struct { + int ival; + double dval; + } + typestr == '|V16' + descr == [('ival','>i4'),('','|V4'),('dval','>f8')] + +It should be clear that any record type could be described using this interface. + +Differences with Array interface (Version 2) +============================================ + +The version 2 interface was very similar. The differences were +largely asthetic. In particular: + +1. The PyArrayInterface structure had no descr member at the end + (and therefore no flag ARR_HAS_DESCR) + +2. The desc member of the PyCObject returned from __array_struct__ was + not specified. Usually, it was the object exposing the array (so + that a reference to it could be kept and destroyed when the + C-object was destroyed). Now it must be a tuple whose first + element is a string with "PyArrayInterface Version #" and whose + second element is the object exposing the array. + +3. The tuple returned from __array_interface__['data'] used to be a + hex-string (now it is an integer or a long integer). + +4. There was no __array_interface__ attribute instead all of the keys + (except for version) in the __array_interface__ dictionary were + their own attribute: Thus to obtain the Python-side information you + had to access separately the attributes: + + * __array_data__ + * __array_shape__ + * __array_strides__ + * __array_typestr__ + * __array_descr__ + * __array_offset__ + * __array_mask__ diff --git a/doc/source/reference/maskedarray.generic.rst b/doc/source/reference/maskedarray.generic.rst index 580c8a3de..7c998ae63 100644 --- a/doc/source/reference/maskedarray.generic.rst +++ b/doc/source/reference/maskedarray.generic.rst @@ -30,6 +30,7 @@ The package ensures that masked entries are not used in computations. As an illustration, let's consider the following dataset:: >>> import numpy as np + >>> import numpy.ma as ma >>> x = np.array([1, 2, 3, -1, 5]) We wish to mark the fourth entry as invalid. The easiest is to create a masked @@ -135,7 +136,7 @@ There are several ways to construct a masked array. Accessing the data ------------------ -The underlying data of a masked array can be accessed through several ways: +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 @@ -148,8 +149,7 @@ The underlying data of a masked array can be accessed through several ways: * 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, invalid data should not be relied on. -If a representation of the array is needed 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. @@ -264,14 +264,14 @@ 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 not work if the masked array - has a *hard* mask, as shown by the :attr:`~MaskedArray.hardmask` attribute. - This feature was introduced to prevent the overwriting of the mask. - To force the unmasking of an entry in such circumstance, the mask has first - to be softened with the :meth:`soften_mask` method before the allocation, - and then re-hardened with :meth:`harden_mask`:: - - >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) + 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 masked_array(data = [1 2 --], mask = [False False True], @@ -287,17 +287,17 @@ To unmask one or several specific entries, we can just assign one or several new masked_array(data = [1 2 --], mask = [False False True], fill_value = 999999) - >>> x.soften_mask() + >>> x.harden_mask() -To unmask all masked entries of a masked array, 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 masked_array(data = [1 2 --], mask = [False False True], fill_value = 999999) - >>> x.mask = nomask + >>> x.mask = ma.nomask >>> x masked_array(data = [1 2 3], mask = [False False False], @@ -364,14 +364,12 @@ 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:`~MaskedArray.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 invalid - data may actually be affected by the operation in some cases and once again - that invalid data should not be relied on. + 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. diff --git a/doc/source/reference/routines.array-creation.rst b/doc/source/reference/routines.array-creation.rst index 25196232a..468ab8aa4 100644 --- a/doc/source/reference/routines.array-creation.rst +++ b/doc/source/reference/routines.array-creation.rst @@ -76,6 +76,7 @@ Numerical ranges logspace meshgrid mgrid + ogrid Building matrices ----------------- diff --git a/doc/source/reference/routines.array-manipulation.rst b/doc/source/reference/routines.array-manipulation.rst index e5163bcfc..2c1a5b200 100644 --- a/doc/source/reference/routines.array-manipulation.rst +++ b/doc/source/reference/routines.array-manipulation.rst @@ -3,8 +3,6 @@ Array manipulation routines .. currentmodule:: numpy -.. toctree:: - Changing array shape ==================== .. autosummary:: @@ -21,7 +19,6 @@ Transpose-like operations .. autosummary:: :toctree: generated/ - rollaxis swapaxes ndarray.T @@ -32,7 +29,6 @@ Changing number of dimensions .. autosummary:: :toctree: generated/ - atleast_1d atleast_2d atleast_3d @@ -59,7 +55,6 @@ Joining arrays .. autosummary:: :toctree: generated/ - append column_stack concatenate dstack @@ -92,6 +87,7 @@ Adding and removing elements delete insert + append resize trim_zeros unique diff --git a/doc/source/reference/routines.fft.rst b/doc/source/reference/routines.fft.rst index e830fcf0d..6c47925ee 100644 --- a/doc/source/reference/routines.fft.rst +++ b/doc/source/reference/routines.fft.rst @@ -1,59 +1,2 @@ .. _routines.fft: - -Fourier transforms (:mod:`numpy.fft`) -************************************* - -.. currentmodule:: numpy.fft - -1-dimensional -------------- -.. autosummary:: - :toctree: generated/ - - fft - ifft - -2-dimensional -------------- -.. autosummary:: - :toctree: generated/ - - fft2 - ifft2 - -N-dimensional -------------- -.. autosummary:: - :toctree: generated/ - - fftn - ifftn - -Hermite symmetric ------------------ -.. autosummary:: - :toctree: generated/ - - hfft - ihfft - -Real-valued ------------ -.. autosummary:: - :toctree: generated/ - - rfft - irfft - rfft2 - irfft2 - rfftn - irfftn - -Helper routines ---------------- -.. autosummary:: - :toctree: generated/ - - fftfreq - fftshift - ifftshift +.. automodule:: numpy.fft diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst index e682f5a57..eb2e9fc4e 100644 --- a/doc/source/reference/routines.rst +++ b/doc/source/reference/routines.rst @@ -27,6 +27,7 @@ Routines routines.ma routines.help routines.other + routines.testing routines.emath routines.matlib routines.dual diff --git a/doc/source/reference/ufuncs.rst b/doc/source/reference/ufuncs.rst index 76b5a97b6..d63486342 100644 --- a/doc/source/reference/ufuncs.rst +++ b/doc/source/reference/ufuncs.rst @@ -46,7 +46,7 @@ understood by four rules: 2. The size in each dimension of the output shape is the maximum of all the input shapes in that dimension. -3. An input can be used in the calculation if it's shape in a particular +3. An input can be used in the calculation if its shape in a particular dimension either matches the output shape or has value exactly 1. 4. If an input has a dimension size of 1 in its shape, the first data @@ -89,7 +89,7 @@ is true: to the other rows, - *c* acts like a (1,6) array and therefore like a (5,6) array - where ``c[:]` is broadcast to every row, and finally, + where ``c[:]`` is broadcast to every row, and finally, - *d* acts like a (5,6) array where the single value is repeated. @@ -332,7 +332,7 @@ and a *dtype* keyword, and the arrays must all have dimension >= 1. The *axis* keyword specifies which axis of the array the reduction will take place over and may be negative, but must be an integer. The *dtype* keyword allows you to manage a very common problem that arises -when naively using `{op}.reduce <ufunc.reduce>`. Sometimes you may +when naively using :ref:`{op}.reduce <ufunc.reduce>`. Sometimes you may have an array of a certain data type and wish to add up all of its elements, but the result does not fit into the data type of the array. This commonly happens if you have an array of single-byte |