diff options
Diffstat (limited to 'numpy/doc')
| -rw-r--r-- | numpy/doc/basics.py | 2 | ||||
| -rw-r--r-- | numpy/doc/creation.py | 53 | ||||
| -rw-r--r-- | numpy/doc/glossary.py | 51 | ||||
| -rw-r--r-- | numpy/doc/misc.py | 218 | ||||
| -rw-r--r-- | numpy/doc/subclassing.py | 23 |
5 files changed, 307 insertions, 40 deletions
diff --git a/numpy/doc/basics.py b/numpy/doc/basics.py index dfb8fe74d..d34c1f303 100644 --- a/numpy/doc/basics.py +++ b/numpy/doc/basics.py @@ -132,6 +132,4 @@ identical behaviour between arrays and scalars, irrespective of whether the value is inside an array or not. NumPy scalars also have many of the same methods arrays do. -See xxx for details. - """ diff --git a/numpy/doc/creation.py b/numpy/doc/creation.py index 1e80e5115..133765678 100644 --- a/numpy/doc/creation.py +++ b/numpy/doc/creation.py @@ -1,6 +1,6 @@ """ ============== -Array creation +Array Creation ============== Introduction @@ -18,17 +18,15 @@ This section will not cover means of replicating, joining, or otherwise expanding or mutating existing arrays. Nor will it cover creating object arrays or record arrays. Both of those are covered in their own sections. -Converting Python array-like objects to numpy arrays +Converting Python array_like Objects to Numpy Arrays ==================================================== In general, numerical data arranged in an array-like structure in Python can be converted to arrays through the use of the array() function. The most obvious examples are lists and tuples. See the documentation for array() for details for -its use. Some -objects may support the array-protocol and allow conversion to arrays this -way. A simple way to find out if the object can be converted to a numpy array -using array() is simply to try it interactively and see if it works! (The -Python Way). +its use. Some objects may support the array-protocol and allow conversion to arrays +this way. A simple way to find out if the object can be converted to a numpy array +using array() is simply to try it interactively and see if it works! (The Python Way). Examples: :: @@ -37,7 +35,7 @@ Examples: :: >>> x = np.array([[1,2.0],[0,0],(1+1j,3.)]) # note mix of tuple and lists, and types >>> x = np.array([[ 1.+0.j, 2.+0.j], [ 0.+0.j, 0.+0.j], [ 1.+1.j, 3.+0.j]]) -Intrinsic numpy array creation +Intrinsic Numpy Array Creation ============================== Numpy has built-in functions for creating arrays from scratch: @@ -65,6 +63,17 @@ examples will be given here: :: Note that there are some subtleties regarding the last usage that the user should be aware of that are described in the arange docstring. +linspace() will create arrays with a specified number of elements, and +spaced equally between the specified beginning and end values. For +example: :: + + >>> np.linspace(1., 4., 6) + array([ 1. , 1.6, 2.2, 2.8, 3.4, 4. ]) + +The advantage of this creation function is that one can guarantee the +number of elements and the starting and end point, which arange() +generally will not do for arbitrary start, stop, and step values. + indices() will create a set of arrays (stacked as a one-higher dimensioned array), one per dimension with each representing variation in that dimension. An examples illustrates much better than a verbal description: :: @@ -75,41 +84,41 @@ An examples illustrates much better than a verbal description: :: This is particularly useful for evaluating functions of multiple dimensions on a regular grid. -Reading arrays from disk +Reading Arrays From Disk ======================== This is presumably the most common case of large array creation. The details, of course, depend greatly on the format of data on disk and so this section can only give general pointers on how to handle various formats. -Standard binary formats +Standard Binary Formats ----------------------- Various fields have standard formats for array data. The following lists the ones with known python libraries to read them and return numpy arrays (there may be others for which it is possible to read and convert to numpy arrays so check the last section as well) +:: -HDF5: PyTables -FITS: PyFITS -Others? xxx + HDF5: PyTables + FITS: PyFITS + Others? xxx Examples of formats that cannot be read directly but for which it is not hard to convert are libraries like PIL (able to read and write many image formats such as jpg, png, etc). -Common ascii formats --------------------- +Common ASCII Formats +------------------------ Comma Separated Value files (CSV) are widely used (and an export and import option for programs like Excel). There are a number of ways of reading these -files in Python. The most convenient ways of reading these are found in pylab -(part of matplotlib) in the xxx function. (list alternatives xxx) +files in Python. There are CSV functions in Python and functions in pylab +(part of matplotlib). -More generic ascii files can be read using the io package in scipy. xxx a few -more details needed... +More generic ascii files can be read using the io package in scipy. -Custom binary formats +Custom Binary Formats --------------------- There are a variety of approaches one can use. If the file has a relatively @@ -120,13 +129,13 @@ read the data, one can wrap that library with a variety of techniques (see xxx) though that certainly is much more work and requires significantly more advanced knowledge to interface with C or C++. -Use of special libraries +Use of Special Libraries ------------------------ There are libraries that can be used to generate arrays for special purposes and it isn't possible to enumerate all of them. The most common uses are use of the many array generation functions in random that can generate arrays of random values, and some utility functions to generate special matrices (e.g. -diagonal, see xxx) +diagonal) """ diff --git a/numpy/doc/glossary.py b/numpy/doc/glossary.py index 6a182adf4..f591a5424 100644 --- a/numpy/doc/glossary.py +++ b/numpy/doc/glossary.py @@ -1,7 +1,7 @@ """ -================= +======== Glossary -================= +======== along an axis Axes are defined for arrays with more than one dimension. A @@ -23,7 +23,7 @@ along an axis >>> x.sum(axis=1) array([ 6, 22, 38]) -array or ndarray +array A homogeneous container of numerical elements. Each element in the array occupies a fixed amount of memory (hence homogeneous), and can be a numerical element of a single type (such as float, int @@ -60,6 +60,9 @@ attribute >>> x.shape (3,) +BLAS + `Basic Linear Algebra Subprograms <http://en.wikipedia.org/wiki/BLAS>`_ + broadcast NumPy can do operations on arrays whose shapes are mismatched:: @@ -79,6 +82,24 @@ broadcast See `doc.broadcasting`_ for more information. +C order + See `row-major` + +column-major + A way to represent items in a N-dimensional array in the 1-dimensional + computer memory. In column-major order, the leftmost index "varies the + fastest": for example the array:: + + [[1, 2, 3], + [4, 5, 6]] + + is represented in the column-major order as:: + + [1, 4, 2, 5, 3, 6] + + Column-major order is also known as the Fortran order, as the Fortran + programming language uses it. + decorator An operator that transforms a function. For example, a ``log`` decorator may be defined to print debugging information upon @@ -128,6 +149,12 @@ dictionary For more information on dictionaries, read the `Python tutorial <http://docs.python.org/tut>`_. +Fortran order + See `column-major` + +flattened + Collapsed to a one-dimensional array. See `ndarray.flatten`_ for details. + immutable An object that cannot be modified after execution is called immutable. Two common examples are strings and tuples. @@ -250,10 +277,28 @@ method >>> x.repeat(2) array([1, 1, 2, 2, 3, 3]) +ndarray + See *array*. + reference If ``a`` is a reference to ``b``, then ``(a is b) == True``. Therefore, ``a`` and ``b`` are different names for the same Python object. +row-major + A way to represent items in a N-dimensional array in the 1-dimensional + computer memory. In row-major order, the rightmost index "varies + the fastest": for example the array:: + + [[1, 2, 3], + [4, 5, 6]] + + is represented in the row-major order as:: + + [1, 2, 3, 4, 5, 6] + + Row-major order is also known as the C order, as the C programming + language uses it. New Numpy arrays are by default in row-major order. + self Often seen in method signatures, ``self`` refers to the instance of the associated class. For example: diff --git a/numpy/doc/misc.py b/numpy/doc/misc.py index e978100bf..1e43f312a 100644 --- a/numpy/doc/misc.py +++ b/numpy/doc/misc.py @@ -1,9 +1,223 @@ """ - ============= Miscellaneous ============= -Placeholder for other tips. +IEEE 754 Floating Point Special Values: +----------------------------------------------- + +Special values defined in numpy: nan, inf, + +NaNs can be used as a poor-man's mask (if you don't care what the +original value was) + +Note: cannot use equality to test NaNs. E.g.: :: + + >>> np.where(myarr == np.nan) + >>> nan == nan # is always False! Use special numpy functions instead. + + >>> np.nan == np.nan + False + >>> myarr = np.array([1., 0., np.nan, 3.]) + >>> myarr[myarr == np.nan] = 0. # doesn't work + >>> myarr + array([ 1., 0., NaN, 3.]) + >>> myarr[np.isnan(myarr)] = 0. # use this instead find + >>> myarr + array([ 1., 0., 0., 3.]) + +Other related special value functions: :: + + isinf(): True if value is inf + isfinite(): True if not nan or inf + nan_to_num(): Map nan to 0, inf to max float, -inf to min float + +The following corresponds to the usual functions except that nans are excluded from +the results: :: + + nansum() + nanmax() + nanmin() + nanargmax() + nanargmin() + + >>> x = np.arange(10.) + >>> x[3] = np.nan + >>> x.sum() + nan + >>> np.nansum(x) + 42.0 + +How numpy handles numerical exceptions + +Default is to "warn" +But this can be changed, and it can be set individually for different kinds +of exceptions. The different behaviors are: :: + + 'ignore' : ignore completely + 'warn' : print a warning (once only) + 'raise' : raise an exception + 'call' : call a user-supplied function (set using seterrcall()) + +These behaviors can be set for all kinds of errors or specific ones: :: + + all: apply to all numeric exceptions + invalid: when NaNs are generated + divide: divide by zero (for integers as well!) + overflow: floating point overflows + underflow: floating point underflows + +Note that integer divide-by-zero is handled by the same machinery. +These behaviors are set on a per-thead basis. + +Examples: +------------ + +:: + + >>> oldsettings = np.seterr(all='warn') + >>> np.zeros(5,dtype=np.float32)/0. + invalid value encountered in divide + >>> j = np.seterr(under='ignore') + >>> np.array([1.e-100])**10 + >>> j = np.seterr(invalid='raise') + >>> np.sqrt(np.array([-1.])) + FloatingPointError: invalid value encountered in sqrt + >>> def errorhandler(errstr, errflag): + ... print "saw stupid error!" + >>> np.seterrcall(errorhandler) + >>> j = np.seterr(all='call') + >>> np.zeros(5, dtype=np.int32)/0 + FloatingPointError: invalid value encountered in divide + saw stupid error! + >>> j = np.seterr(**oldsettings) # restore previous + # error-handling settings + +Interfacing to C: +----------------- +Only a survey the choices. Little detail on how each works. + +1) Bare metal, wrap your own C-code manually. + + - Plusses: + + - Efficient + - No dependencies on other tools + + - Minuses: + + - Lots of learning overhead: + + - need to learn basics of Python C API + - need to learn basics of numpy C API + - need to learn how to handle reference counting and love it. + + - Reference counting often difficult to get right. + + - getting it wrong leads to memory leaks, and worse, segfaults + + - API will change for Python 3.0! + +2) pyrex + + - Plusses: + + - avoid learning C API's + - no dealing with reference counting + - can code in psuedo python and generate C code + - can also interface to existing C code + - should shield you from changes to Python C api + - become pretty popular within Python community + + - Minuses: + + - Can write code in non-standard form which may become obsolete + - Not as flexible as manual wrapping + - Maintainers not easily adaptable to new features + +Thus: + +3) cython - fork of pyrex to allow needed features for SAGE + + - being considered as the standard scipy/numpy wrapping tool + - fast indexing support for arrays + +4) ctypes + + - Plusses: + + - part of Python standard library + - good for interfacing to existing sharable libraries, particularly + Windows DLLs + - avoids API/reference counting issues + - good numpy support: arrays have all these in their ctypes + attribute: :: + + a.ctypes.data a.ctypes.get_strides + a.ctypes.data_as a.ctypes.shape + a.ctypes.get_as_parameter a.ctypes.shape_as + a.ctypes.get_data a.ctypes.strides + a.ctypes.get_shape a.ctypes.strides_as + + - Minuses: + + - can't use for writing code to be turned into C extensions, only a wrapper tool. + +5) SWIG (automatic wrapper generator) + + - Plusses: + + - around a long time + - multiple scripting language support + - C++ support + - Good for wrapping large (many functions) existing C libraries + + - Minuses: + + - generates lots of code between Python and the C code + + - can cause performance problems that are nearly impossible to optimize out + + - interface files can be hard to write + - doesn't necessarily avoid reference counting issues or needing to know API's + +7) Weave + + - Plusses: + + - Phenomenal tool + - can turn many numpy expressions into C code + - dynamic compiling and loading of generated C code + - can embed pure C code in Python module and have weave extract, generate interfaces + and compile, etc. + + - Minuses: + + - Future uncertain--lacks a champion + +8) Psyco + + - Plusses: + + - Turns pure python into efficient machine code through jit-like optimizations + - very fast when it optimizes well + + - Minuses: + + - Only on intel (windows?) + - Doesn't do much for numpy? + +Interfacing to Fortran: +----------------------- +Fortran: Clear choice is f2py. (Pyfort is an older alternative, but not supported +any longer) + +Interfacing to C++: +------------------- +1) CXX +2) Boost.python +3) SWIG +4) Sage has used cython to wrap C++ (not pretty, but it can be done) +5) SIP (used mainly in PyQT) """ diff --git a/numpy/doc/subclassing.py b/numpy/doc/subclassing.py index 859ab32f9..bbd44f8ee 100644 --- a/numpy/doc/subclassing.py +++ b/numpy/doc/subclassing.py @@ -20,17 +20,17 @@ why subclassing works as it does. ndarrays and object creation ============================ The creation of ndarrays is complicated by the need to return views of -ndarrays, that are also ndarrays. For example:: - - >>> import numpy as np - >>> arr = np.zeros((3,)) - >>> type(arr) - <type 'numpy.ndarray'> - >>> v = arr[1:] - >>> type(v) - <type 'numpy.ndarray'> - >>> v is arr - False +ndarrays, that are also ndarrays. For example: + +>>> import numpy as np +>>> arr = np.zeros((3,)) +>>> type(arr) +<type 'numpy.ndarray'> +>>> v = arr[1:] +>>> type(v) +<type 'numpy.ndarray'> +>>> v is arr +False So, when we take a view (here a slice) from the ndarray, we return a new ndarray, that points to the data in the original. When we @@ -148,6 +148,7 @@ Simple example - adding an extra attribute to ndarray ----------------------------------------------------- :: + import numpy as np class InfoArray(np.ndarray): |