From 5c86844c34674e3d580ac2cd12ef171e18130b13 Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Sat, 23 Aug 2008 23:17:23 +0000 Subject: Move documentation outside of source tree. Remove `doc` import from __init__. --- numpy/doc/creation.py | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 numpy/doc/creation.py (limited to 'numpy/doc/creation.py') diff --git a/numpy/doc/creation.py b/numpy/doc/creation.py new file mode 100644 index 000000000..1e80e5115 --- /dev/null +++ b/numpy/doc/creation.py @@ -0,0 +1,132 @@ +""" +============== +Array creation +============== + +Introduction +============ + +There are 5 general mechanisms for creating arrays: + +1) Conversion from other Python structures (e.g., lists, tuples) +2) Intrinsic numpy array array creation objects (e.g., arange, ones, zeros, etc.) +3) Reading arrays from disk, either from standard or custom formats +4) Creating arrays from raw bytes through the use of strings or buffers +5) Use of special library functions (e.g., random) + +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 +==================================================== + +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). + +Examples: :: + + >>> x = np.array([2,3,1,0]) + >>> x = np.array([2, 3, 1, 0]) + >>> 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 +============================== + +Numpy has built-in functions for creating arrays from scratch: + +zeros(shape) will create an array filled with 0 values with the specified +shape. The default dtype is float64. + +``>>> np.zeros((2, 3)) +array([[ 0., 0., 0.], [ 0., 0., 0.]])`` + +ones(shape) will create an array filled with 1 values. It is identical to +zeros in all other respects. + +arange() will create arrays with regularly incrementing values. Check the +docstring for complete information on the various ways it can be used. A few +examples will be given here: :: + + >>> np.arange(10) + array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) + >>> np.arange(2, 10, dtype=np.float) + array([ 2., 3., 4., 5., 6., 7., 8., 9.]) + >>> np.arange(2, 3, 0.1) + array([ 2. , 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9]) + +Note that there are some subtleties regarding the last usage that the user +should be aware of that are described in the arange docstring. + +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: :: + + >>> np.indices((3,3)) + array([[[0, 0, 0], [1, 1, 1], [2, 2, 2]], [[0, 1, 2], [0, 1, 2], [0, 1, 2]]]) + +This is particularly useful for evaluating functions of multiple dimensions on +a regular grid. + +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 +----------------------- + +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 + +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 +-------------------- + +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) + +More generic ascii files can be read using the io package in scipy. xxx a few +more details needed... + +Custom binary formats +--------------------- + +There are a variety of approaches one can use. If the file has a relatively +simple format then one can write a simple I/O library and use the numpy +fromfile() function and .tofile() method to read and write numpy arrays +directly (mind your byteorder though!) If a good C or C++ library exists that +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 +------------------------ + +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) + +""" -- cgit v1.2.1