Skip to content

Commit

Permalink
Merge from the doc wiki
Browse files Browse the repository at this point in the history
pv committed Mar 24, 2009
1 parent 940a7d3 commit 7b751f6
Showing 36 changed files with 4,776 additions and 1,261 deletions.
7 changes: 3 additions & 4 deletions doc/source/about.rst
Original file line number Diff line number Diff line change
@@ -14,8 +14,8 @@ needed for scientific computing with Python. This package contains:

Besides its obvious scientific uses, *NumPy* can also be used as an
efficient multi-dimensional container of generic data. Arbitrary
data-types can be defined. This allows *NumPy* to seamlessly and
speedily integrate with a wide-variety of databases.
data types can be defined. This allows *NumPy* to seamlessly and
speedily integrate with a wide variety of databases.

NumPy is a successor for two earlier scientific Python libraries:
NumPy derives from the old *Numeric* code base and can be used
@@ -25,7 +25,7 @@ by *Numarray* and can also be used to replace *Numarray*.
NumPy community
---------------

Numpy is a distributed, volunteer open-source project. *You* can help
Numpy is a distributed, volunteer, open-source project. *You* can help
us make it better; if you believe something should be improved either
in functionality or in documentation, don't hesitate to contact us --- or
even better, contact us and participate in fixing the problem.
@@ -63,4 +63,3 @@ examples assume that you have first entered::
>>> import numpy as np

before running the examples.

6 changes: 3 additions & 3 deletions doc/source/reference/arrays.classes.rst
Original file line number Diff line number Diff line change
@@ -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:

125 changes: 122 additions & 3 deletions doc/source/reference/arrays.interface.rst
Original file line number Diff line number Diff line change
@@ -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__
38 changes: 18 additions & 20 deletions doc/source/reference/maskedarray.generic.rst
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions doc/source/reference/routines.array-creation.rst
Original file line number Diff line number Diff line change
@@ -76,6 +76,7 @@ Numerical ranges
logspace
meshgrid
mgrid
ogrid

Building matrices
-----------------
6 changes: 1 addition & 5 deletions doc/source/reference/routines.array-manipulation.rst
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 7b751f6

Please sign in to comment.