Chris@87: """ Chris@87: ======== Chris@87: Glossary Chris@87: ======== Chris@87: Chris@87: .. glossary:: Chris@87: Chris@87: along an axis Chris@87: Axes are defined for arrays with more than one dimension. A Chris@87: 2-dimensional array has two corresponding axes: the first running Chris@87: vertically downwards across rows (axis 0), and the second running Chris@87: horizontally across columns (axis 1). Chris@87: Chris@87: Many operation can take place along one of these axes. For example, Chris@87: we can sum each row of an array, in which case we operate along Chris@87: columns, or axis 1:: Chris@87: Chris@87: >>> x = np.arange(12).reshape((3,4)) Chris@87: Chris@87: >>> x Chris@87: array([[ 0, 1, 2, 3], Chris@87: [ 4, 5, 6, 7], Chris@87: [ 8, 9, 10, 11]]) Chris@87: Chris@87: >>> x.sum(axis=1) Chris@87: array([ 6, 22, 38]) Chris@87: Chris@87: array Chris@87: A homogeneous container of numerical elements. Each element in the Chris@87: array occupies a fixed amount of memory (hence homogeneous), and Chris@87: can be a numerical element of a single type (such as float, int Chris@87: or complex) or a combination (such as ``(float, int, float)``). Each Chris@87: array has an associated data-type (or ``dtype``), which describes Chris@87: the numerical type of its elements:: Chris@87: Chris@87: >>> x = np.array([1, 2, 3], float) Chris@87: Chris@87: >>> x Chris@87: array([ 1., 2., 3.]) Chris@87: Chris@87: >>> x.dtype # floating point number, 64 bits of memory per element Chris@87: dtype('float64') Chris@87: Chris@87: Chris@87: # More complicated data type: each array element is a combination of Chris@87: # and integer and a floating point number Chris@87: >>> np.array([(1, 2.0), (3, 4.0)], dtype=[('x', int), ('y', float)]) Chris@87: array([(1, 2.0), (3, 4.0)], Chris@87: dtype=[('x', '>> x = np.array([1, 2, 3]) Chris@87: >>> x.shape Chris@87: (3,) Chris@87: Chris@87: BLAS Chris@87: `Basic Linear Algebra Subprograms `_ Chris@87: Chris@87: broadcast Chris@87: NumPy can do operations on arrays whose shapes are mismatched:: Chris@87: Chris@87: >>> x = np.array([1, 2]) Chris@87: >>> y = np.array([[3], [4]]) Chris@87: Chris@87: >>> x Chris@87: array([1, 2]) Chris@87: Chris@87: >>> y Chris@87: array([[3], Chris@87: [4]]) Chris@87: Chris@87: >>> x + y Chris@87: array([[4, 5], Chris@87: [5, 6]]) Chris@87: Chris@87: See `doc.broadcasting`_ for more information. Chris@87: Chris@87: C order Chris@87: See `row-major` Chris@87: Chris@87: column-major Chris@87: A way to represent items in a N-dimensional array in the 1-dimensional Chris@87: computer memory. In column-major order, the leftmost index "varies the Chris@87: fastest": for example the array:: Chris@87: Chris@87: [[1, 2, 3], Chris@87: [4, 5, 6]] Chris@87: Chris@87: is represented in the column-major order as:: Chris@87: Chris@87: [1, 4, 2, 5, 3, 6] Chris@87: Chris@87: Column-major order is also known as the Fortran order, as the Fortran Chris@87: programming language uses it. Chris@87: Chris@87: decorator Chris@87: An operator that transforms a function. For example, a ``log`` Chris@87: decorator may be defined to print debugging information upon Chris@87: function execution:: Chris@87: Chris@87: >>> def log(f): Chris@87: ... def new_logging_func(*args, **kwargs): Chris@87: ... print "Logging call with parameters:", args, kwargs Chris@87: ... return f(*args, **kwargs) Chris@87: ... Chris@87: ... return new_logging_func Chris@87: Chris@87: Now, when we define a function, we can "decorate" it using ``log``:: Chris@87: Chris@87: >>> @log Chris@87: ... def add(a, b): Chris@87: ... return a + b Chris@87: Chris@87: Calling ``add`` then yields: Chris@87: Chris@87: >>> add(1, 2) Chris@87: Logging call with parameters: (1, 2) {} Chris@87: 3 Chris@87: Chris@87: dictionary Chris@87: Resembling a language dictionary, which provides a mapping between Chris@87: words and descriptions thereof, a Python dictionary is a mapping Chris@87: between two objects:: Chris@87: Chris@87: >>> x = {1: 'one', 'two': [1, 2]} Chris@87: Chris@87: Here, `x` is a dictionary mapping keys to values, in this case Chris@87: the integer 1 to the string "one", and the string "two" to Chris@87: the list ``[1, 2]``. The values may be accessed using their Chris@87: corresponding keys:: Chris@87: Chris@87: >>> x[1] Chris@87: 'one' Chris@87: Chris@87: >>> x['two'] Chris@87: [1, 2] Chris@87: Chris@87: Note that dictionaries are not stored in any specific order. Also, Chris@87: most mutable (see *immutable* below) objects, such as lists, may not Chris@87: be used as keys. Chris@87: Chris@87: For more information on dictionaries, read the Chris@87: `Python tutorial `_. Chris@87: Chris@87: Fortran order Chris@87: See `column-major` Chris@87: Chris@87: flattened Chris@87: Collapsed to a one-dimensional array. See `ndarray.flatten`_ for details. Chris@87: Chris@87: immutable Chris@87: An object that cannot be modified after execution is called Chris@87: immutable. Two common examples are strings and tuples. Chris@87: Chris@87: instance Chris@87: A class definition gives the blueprint for constructing an object:: Chris@87: Chris@87: >>> class House(object): Chris@87: ... wall_colour = 'white' Chris@87: Chris@87: Yet, we have to *build* a house before it exists:: Chris@87: Chris@87: >>> h = House() # build a house Chris@87: Chris@87: Now, ``h`` is called a ``House`` instance. An instance is therefore Chris@87: a specific realisation of a class. Chris@87: Chris@87: iterable Chris@87: A sequence that allows "walking" (iterating) over items, typically Chris@87: using a loop such as:: Chris@87: Chris@87: >>> x = [1, 2, 3] Chris@87: >>> [item**2 for item in x] Chris@87: [1, 4, 9] Chris@87: Chris@87: It is often used in combintion with ``enumerate``:: Chris@87: >>> keys = ['a','b','c'] Chris@87: >>> for n, k in enumerate(keys): Chris@87: ... print "Key %d: %s" % (n, k) Chris@87: ... Chris@87: Key 0: a Chris@87: Key 1: b Chris@87: Key 2: c Chris@87: Chris@87: list Chris@87: A Python container that can hold any number of objects or items. Chris@87: The items do not have to be of the same type, and can even be Chris@87: lists themselves:: Chris@87: Chris@87: >>> x = [2, 2.0, "two", [2, 2.0]] Chris@87: Chris@87: The list `x` contains 4 items, each which can be accessed individually:: Chris@87: Chris@87: >>> x[2] # the string 'two' Chris@87: 'two' Chris@87: Chris@87: >>> x[3] # a list, containing an integer 2 and a float 2.0 Chris@87: [2, 2.0] Chris@87: Chris@87: It is also possible to select more than one item at a time, Chris@87: using *slicing*:: Chris@87: Chris@87: >>> x[0:2] # or, equivalently, x[:2] Chris@87: [2, 2.0] Chris@87: Chris@87: In code, arrays are often conveniently expressed as nested lists:: Chris@87: Chris@87: Chris@87: >>> np.array([[1, 2], [3, 4]]) Chris@87: array([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: For more information, read the section on lists in the `Python Chris@87: tutorial `_. For a mapping Chris@87: type (key-value), see *dictionary*. Chris@87: Chris@87: mask Chris@87: A boolean array, used to select only certain elements for an operation:: Chris@87: Chris@87: >>> x = np.arange(5) Chris@87: >>> x Chris@87: array([0, 1, 2, 3, 4]) Chris@87: Chris@87: >>> mask = (x > 2) Chris@87: >>> mask Chris@87: array([False, False, False, True, True], dtype=bool) Chris@87: Chris@87: >>> x[mask] = -1 Chris@87: >>> x Chris@87: array([ 0, 1, 2, -1, -1]) Chris@87: Chris@87: masked array Chris@87: Array that suppressed values indicated by a mask:: Chris@87: Chris@87: >>> x = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True]) Chris@87: >>> x Chris@87: masked_array(data = [-- 2.0 --], Chris@87: mask = [ True False True], Chris@87: fill_value = 1e+20) Chris@87: Chris@87: Chris@87: >>> x + [1, 2, 3] Chris@87: masked_array(data = [-- 4.0 --], Chris@87: mask = [ True False True], Chris@87: fill_value = 1e+20) Chris@87: Chris@87: Chris@87: Chris@87: Masked arrays are often used when operating on arrays containing Chris@87: missing or invalid entries. Chris@87: Chris@87: matrix Chris@87: A 2-dimensional ndarray that preserves its two-dimensional nature Chris@87: throughout operations. It has certain special operations, such as ``*`` Chris@87: (matrix multiplication) and ``**`` (matrix power), defined:: Chris@87: Chris@87: >>> x = np.mat([[1, 2], [3, 4]]) Chris@87: Chris@87: >>> x Chris@87: matrix([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: >>> x**2 Chris@87: matrix([[ 7, 10], Chris@87: [15, 22]]) Chris@87: Chris@87: method Chris@87: A function associated with an object. For example, each ndarray has a Chris@87: method called ``repeat``:: Chris@87: Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: Chris@87: >>> x.repeat(2) Chris@87: array([1, 1, 2, 2, 3, 3]) Chris@87: Chris@87: ndarray Chris@87: See *array*. Chris@87: Chris@87: reference Chris@87: If ``a`` is a reference to ``b``, then ``(a is b) == True``. Therefore, Chris@87: ``a`` and ``b`` are different names for the same Python object. Chris@87: Chris@87: row-major Chris@87: A way to represent items in a N-dimensional array in the 1-dimensional Chris@87: computer memory. In row-major order, the rightmost index "varies Chris@87: the fastest": for example the array:: Chris@87: Chris@87: [[1, 2, 3], Chris@87: [4, 5, 6]] Chris@87: Chris@87: is represented in the row-major order as:: Chris@87: Chris@87: [1, 2, 3, 4, 5, 6] Chris@87: Chris@87: Row-major order is also known as the C order, as the C programming Chris@87: language uses it. New Numpy arrays are by default in row-major order. Chris@87: Chris@87: self Chris@87: Often seen in method signatures, ``self`` refers to the instance Chris@87: of the associated class. For example: Chris@87: Chris@87: >>> class Paintbrush(object): Chris@87: ... color = 'blue' Chris@87: ... Chris@87: ... def paint(self): Chris@87: ... print "Painting the city %s!" % self.color Chris@87: ... Chris@87: >>> p = Paintbrush() Chris@87: >>> p.color = 'red' Chris@87: >>> p.paint() # self refers to 'p' Chris@87: Painting the city red! Chris@87: Chris@87: slice Chris@87: Used to select only certain elements from a sequence:: Chris@87: Chris@87: >>> x = range(5) Chris@87: >>> x Chris@87: [0, 1, 2, 3, 4] Chris@87: Chris@87: >>> x[1:3] # slice from 1 to 3 (excluding 3 itself) Chris@87: [1, 2] Chris@87: Chris@87: >>> x[1:5:2] # slice from 1 to 5, but skipping every second element Chris@87: [1, 3] Chris@87: Chris@87: >>> x[::-1] # slice a sequence in reverse Chris@87: [4, 3, 2, 1, 0] Chris@87: Chris@87: Arrays may have more than one dimension, each which can be sliced Chris@87: individually:: Chris@87: Chris@87: >>> x = np.array([[1, 2], [3, 4]]) Chris@87: >>> x Chris@87: array([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: >>> x[:, 1] Chris@87: array([2, 4]) Chris@87: Chris@87: tuple Chris@87: A sequence that may contain a variable number of types of any Chris@87: kind. A tuple is immutable, i.e., once constructed it cannot be Chris@87: changed. Similar to a list, it can be indexed and sliced:: Chris@87: Chris@87: >>> x = (1, 'one', [1, 2]) Chris@87: Chris@87: >>> x Chris@87: (1, 'one', [1, 2]) Chris@87: Chris@87: >>> x[0] Chris@87: 1 Chris@87: Chris@87: >>> x[:2] Chris@87: (1, 'one') Chris@87: Chris@87: A useful concept is "tuple unpacking", which allows variables to Chris@87: be assigned to the contents of a tuple:: Chris@87: Chris@87: >>> x, y = (1, 2) Chris@87: >>> x, y = 1, 2 Chris@87: Chris@87: This is often used when a function returns multiple values: Chris@87: Chris@87: >>> def return_many(): Chris@87: ... return 1, 'alpha', None Chris@87: Chris@87: >>> a, b, c = return_many() Chris@87: >>> a, b, c Chris@87: (1, 'alpha', None) Chris@87: Chris@87: >>> a Chris@87: 1 Chris@87: >>> b Chris@87: 'alpha' Chris@87: Chris@87: ufunc Chris@87: Universal function. A fast element-wise array operation. Examples include Chris@87: ``add``, ``sin`` and ``logical_or``. Chris@87: Chris@87: view Chris@87: An array that does not own its data, but refers to another array's Chris@87: data instead. For example, we may create a view that only shows Chris@87: every second element of another array:: Chris@87: Chris@87: >>> x = np.arange(5) Chris@87: >>> x Chris@87: array([0, 1, 2, 3, 4]) Chris@87: Chris@87: >>> y = x[::2] Chris@87: >>> y Chris@87: array([0, 2, 4]) Chris@87: Chris@87: >>> x[0] = 3 # changing x changes y as well, since y is a view on x Chris@87: >>> y Chris@87: array([3, 2, 4]) Chris@87: Chris@87: wrapper Chris@87: Python is a high-level (highly abstracted, or English-like) language. Chris@87: This abstraction comes at a price in execution speed, and sometimes Chris@87: it becomes necessary to use lower level languages to do fast Chris@87: computations. A wrapper is code that provides a bridge between Chris@87: high and the low level languages, allowing, e.g., Python to execute Chris@87: code written in C or Fortran. Chris@87: Chris@87: Examples include ctypes, SWIG and Cython (which wraps C and C++) Chris@87: and f2py (which wraps Fortran). Chris@87: Chris@87: """ Chris@87: from __future__ import division, absolute_import, print_function