Chris@87: """ Chris@87: ============== Chris@87: Array Creation Chris@87: ============== Chris@87: Chris@87: Introduction Chris@87: ============ Chris@87: Chris@87: There are 5 general mechanisms for creating arrays: Chris@87: Chris@87: 1) Conversion from other Python structures (e.g., lists, tuples) Chris@87: 2) Intrinsic numpy array array creation objects (e.g., arange, ones, zeros, Chris@87: etc.) Chris@87: 3) Reading arrays from disk, either from standard or custom formats Chris@87: 4) Creating arrays from raw bytes through the use of strings or buffers Chris@87: 5) Use of special library functions (e.g., random) Chris@87: Chris@87: This section will not cover means of replicating, joining, or otherwise Chris@87: expanding or mutating existing arrays. Nor will it cover creating object Chris@87: arrays or record arrays. Both of those are covered in their own sections. Chris@87: Chris@87: Converting Python array_like Objects to Numpy Arrays Chris@87: ==================================================== Chris@87: Chris@87: In general, numerical data arranged in an array-like structure in Python can Chris@87: be converted to arrays through the use of the array() function. The most Chris@87: obvious examples are lists and tuples. See the documentation for array() for Chris@87: details for its use. Some objects may support the array-protocol and allow Chris@87: conversion to arrays this way. A simple way to find out if the object can be Chris@87: converted to a numpy array using array() is simply to try it interactively and Chris@87: see if it works! (The Python Way). Chris@87: Chris@87: Examples: :: Chris@87: Chris@87: >>> x = np.array([2,3,1,0]) Chris@87: >>> x = np.array([2, 3, 1, 0]) Chris@87: >>> x = np.array([[1,2.0],[0,0],(1+1j,3.)]) # note mix of tuple and lists, Chris@87: and types Chris@87: >>> x = np.array([[ 1.+0.j, 2.+0.j], [ 0.+0.j, 0.+0.j], [ 1.+1.j, 3.+0.j]]) Chris@87: Chris@87: Intrinsic Numpy Array Creation Chris@87: ============================== Chris@87: Chris@87: Numpy has built-in functions for creating arrays from scratch: Chris@87: Chris@87: zeros(shape) will create an array filled with 0 values with the specified Chris@87: shape. The default dtype is float64. Chris@87: Chris@87: ``>>> np.zeros((2, 3)) Chris@87: array([[ 0., 0., 0.], [ 0., 0., 0.]])`` Chris@87: Chris@87: ones(shape) will create an array filled with 1 values. It is identical to Chris@87: zeros in all other respects. Chris@87: Chris@87: arange() will create arrays with regularly incrementing values. Check the Chris@87: docstring for complete information on the various ways it can be used. A few Chris@87: examples will be given here: :: Chris@87: Chris@87: >>> np.arange(10) Chris@87: array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) Chris@87: >>> np.arange(2, 10, dtype=np.float) Chris@87: array([ 2., 3., 4., 5., 6., 7., 8., 9.]) Chris@87: >>> np.arange(2, 3, 0.1) Chris@87: array([ 2. , 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9]) Chris@87: Chris@87: Note that there are some subtleties regarding the last usage that the user Chris@87: should be aware of that are described in the arange docstring. Chris@87: Chris@87: linspace() will create arrays with a specified number of elements, and Chris@87: spaced equally between the specified beginning and end values. For Chris@87: example: :: Chris@87: Chris@87: >>> np.linspace(1., 4., 6) Chris@87: array([ 1. , 1.6, 2.2, 2.8, 3.4, 4. ]) Chris@87: Chris@87: The advantage of this creation function is that one can guarantee the Chris@87: number of elements and the starting and end point, which arange() Chris@87: generally will not do for arbitrary start, stop, and step values. Chris@87: Chris@87: indices() will create a set of arrays (stacked as a one-higher dimensioned Chris@87: array), one per dimension with each representing variation in that dimension. Chris@87: An example illustrates much better than a verbal description: :: Chris@87: Chris@87: >>> np.indices((3,3)) Chris@87: array([[[0, 0, 0], [1, 1, 1], [2, 2, 2]], [[0, 1, 2], [0, 1, 2], [0, 1, 2]]]) Chris@87: Chris@87: This is particularly useful for evaluating functions of multiple dimensions on Chris@87: a regular grid. Chris@87: Chris@87: Reading Arrays From Disk Chris@87: ======================== Chris@87: Chris@87: This is presumably the most common case of large array creation. The details, Chris@87: of course, depend greatly on the format of data on disk and so this section Chris@87: can only give general pointers on how to handle various formats. Chris@87: Chris@87: Standard Binary Formats Chris@87: ----------------------- Chris@87: Chris@87: Various fields have standard formats for array data. The following lists the Chris@87: ones with known python libraries to read them and return numpy arrays (there Chris@87: may be others for which it is possible to read and convert to numpy arrays so Chris@87: check the last section as well) Chris@87: :: Chris@87: Chris@87: HDF5: PyTables Chris@87: FITS: PyFITS Chris@87: Chris@87: Examples of formats that cannot be read directly but for which it is not hard to Chris@87: convert are those formats supported by libraries like PIL (able to read and Chris@87: write many image formats such as jpg, png, etc). Chris@87: Chris@87: Common ASCII Formats Chris@87: ------------------------ Chris@87: Chris@87: Comma Separated Value files (CSV) are widely used (and an export and import Chris@87: option for programs like Excel). There are a number of ways of reading these Chris@87: files in Python. There are CSV functions in Python and functions in pylab Chris@87: (part of matplotlib). Chris@87: Chris@87: More generic ascii files can be read using the io package in scipy. Chris@87: Chris@87: Custom Binary Formats Chris@87: --------------------- Chris@87: Chris@87: There are a variety of approaches one can use. If the file has a relatively Chris@87: simple format then one can write a simple I/O library and use the numpy Chris@87: fromfile() function and .tofile() method to read and write numpy arrays Chris@87: directly (mind your byteorder though!) If a good C or C++ library exists that Chris@87: read the data, one can wrap that library with a variety of techniques though Chris@87: that certainly is much more work and requires significantly more advanced Chris@87: knowledge to interface with C or C++. Chris@87: Chris@87: Use of Special Libraries Chris@87: ------------------------ Chris@87: Chris@87: There are libraries that can be used to generate arrays for special purposes Chris@87: and it isn't possible to enumerate all of them. The most common uses are use Chris@87: of the many array generation functions in random that can generate arrays of Chris@87: random values, and some utility functions to generate special matrices (e.g. Chris@87: diagonal). Chris@87: Chris@87: """ Chris@87: from __future__ import division, absolute_import, print_function